@blogic-cz/agent-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Blogic s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @blogic-cz/agent-tools
+
+Safe CLI wrappers for AI coding agents. 6 tools for GitHub, databases, Kubernetes, Azure DevOps, logs, and OpenCode sessions — with JSON5 config and a credential guard that blocks agents from touching secrets.
+
+## Why
+
+AI agents need CLI access. Giving them raw `gh`, `kubectl`, `psql` is dangerous — they can leak credentials, hit production, or run destructive commands.
+
+These tools wrap each CLI with:
+
+- **Security guardrails** — blocked paths, secret detection, dangerous command filtering
+- **Audit trail** — every command goes through a wrapper, not raw shell
+- **Project config** — agents use the right cluster, namespace, and database without guessing
+- **Consistent output** — structured JSON or token-efficient TOON format for LLM consumption
+
+## Installation
+
+```bash
+bun add @blogic-cz/agent-tools
+```
+
+**Requirements:** [Bun](https://bun.sh/) >=1.0.0
+
+### For agents reading this
+
+Clone the repo and look at the source. The tools are in `src/`, each tool is self-contained:
+
+```bash
+git clone https://github.com/blogic-cz/agent-tools.git
+ls src/  # gh-tool/ db-tool/ k8s-tool/ az-tool/ logs-tool/ session-tool/ credential-guard/
+```
+
+## Quick Start
+
+1. Install the package in your project
+2. Create `agent-tools.json5` in your project root:
+
+```json5
+{
+  $schema: "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+  kubernetes: {
+    default: {
+      clusterId: "your-cluster-id",
+      namespaces: { test: "your-ns-test", prod: "your-ns-prod" },
+    },
+  },
+  logs: {
+    default: {
+      localDir: "apps/web-app/logs",
+      remotePath: "/app/logs",
+    },
+  },
+}
+```
+
+3. Run tools:
+
+```bash
+npx agent-tools-gh pr list
+npx agent-tools-k8s kubectl -n prod-ns get pods
+npx agent-tools-logs list --env local
+```
+
+4. Hook up the credential guard in your agent config (Claude Code, OpenCode, etc.):
+
+```typescript
+import { handleToolExecuteBefore } from "@blogic-cz/agent-tools/credential-guard";
+
+export default { handleToolExecuteBefore };
+```
+
+## Tools
+
+| Binary                | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `agent-tools-gh`      | GitHub CLI wrapper — PR management, issues, workflows           |
+| `agent-tools-db`      | Database query tool — SQL execution, schema introspection       |
+| `agent-tools-k8s`     | Kubernetes tool — kubectl with config-driven context resolution |
+| `agent-tools-az`      | Azure DevOps tool — pipelines, builds, repos                    |
+| `agent-tools-logs`    | Application logs — read local and remote (k8s pod) logs         |
+| `agent-tools-session` | OpenCode session browser — list, read, search sessions          |
+
+All tools support `--help` for full usage documentation.
+
+## Configuration
+
+Config is loaded from `agent-tools.json5` (or `agent-tools.json`) by walking up from the current working directory. Missing config = zero-config mode (works for `gh-tool`; others require config).
+
+### IDE Autocompletion
+
+Add `$schema` to your config file:
+
+```json5
+{
+  $schema: "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+}
+```
+
+### Named Profiles
+
+Each tool section supports multiple named profiles. Select with `--profile <name>`:
+
+```json5
+{
+  azure: {
+    default: { organization: "https://dev.azure.com/main-org", defaultProject: "platform" },
+    legacy: { organization: "https://dev.azure.com/old-org", defaultProject: "app" },
+  },
+}
+```
+
+```bash
+npx agent-tools-az pipeline list                    # uses "default" profile
+npx agent-tools-az pipeline list --profile legacy   # uses "legacy" profile
+```
+
+**Profile resolution:** `--profile` flag > auto-select (single profile) > `"default"` key > error.
+
+### Full Config Reference
+
+See [`examples/agent-tools.json5`](./examples/agent-tools.json5) for a complete example with all options documented.
+
+## Environment Variables
+
+Secrets are **never** stored in the config file. Use environment variables:
+
+| Variable           | Used By | Description                                               |
+| ------------------ | ------- | --------------------------------------------------------- |
+| `AGENT_TOOLS_DB_*` | db-tool | DB passwords (name defined by `passwordEnvVar` in config) |
+| `GITHUB_TOKEN`     | gh-tool | GitHub API token (falls back to `gh` CLI auth)            |
+
+### Setting up credentials
+
+The config file only references env var **names** (via `passwordEnvVar`), never actual secrets. Set the values in your shell:
+
+**macOS / Linux** — add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export AGENT_TOOLS_DB_PASSWORD="your-password"
+export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
+```
+
+**Windows** — PowerShell (persistent, user-level):
+
+```powershell
+[Environment]::SetEnvironmentVariable("AGENT_TOOLS_DB_PASSWORD", "your-password", "User")
+[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_xxxxxxxxxxxx", "User")
+```
+
+Restart your terminal after adding env vars. The credential guard ensures these values never leak into agent output.
+
+## Credential Guard
+
+The guard blocks agents from accessing sensitive files, leaking secrets, and running dangerous commands. Every block message links to the source — if an agent thinks a block is wrong, it can fork the repo and submit a PR.
+
+**What it blocks:**
+
+- Reads of secret files (`.env`, `.pem`, `.key`, `.ssh/`, etc.)
+- Writes containing detected secrets (API keys, tokens, passwords)
+- Dangerous shell patterns (`printenv`, `cat .env`, etc.)
+- Direct CLI usage (`gh`, `kubectl`, `psql`, `az`) — must use wrapper tools
+
+### Setup for Claude Code
+
+Claude Code uses shell command hooks. The package ships a ready-made wrapper script.
+
+1. Add to `.claude/settings.json` (or `.claude/settings.local.json` for gitignored config):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun node_modules/@blogic-cz/agent-tools/src/credential-guard/claude-hook.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+That's it. The hook reads tool input from stdin, runs the guard, and exits with code 2 (blocked + reason on stderr) or 0 (allowed).
+
+### Setup for OpenCode
+
+OpenCode loads plugins automatically from `.opencode/plugins/`. Create a plugin file:
+
+**`.opencode/plugins/credential-guard.ts`**
+
+```typescript
+import { handleToolExecuteBefore } from "@blogic-cz/agent-tools/credential-guard";
+
+export const CredentialGuard = async () => ({
+  "tool.execute.before": handleToolExecuteBefore,
+});
+```
+
+If the package isn't already in your project dependencies, add a `.opencode/package.json`:
+
+```json
+{
+  "dependencies": {
+    "@blogic-cz/agent-tools": "*"
+  }
+}
+```
+
+OpenCode installs plugin dependencies automatically at startup.
+
+### Custom patterns
+
+Use the `credentialGuard` config section to extend built-in defaults (arrays are merged, not replaced):
+
+```json5
+{
+  credentialGuard: {
+    additionalBlockedPaths: ["private/secrets/"],
+    additionalAllowedPaths: ["apps/web-app/.env.test"],
+    additionalBlockedCliTools: [{ tool: "helm", suggestion: "Use agent-tools-k8s instead" }],
+    additionalDangerousBashPatterns: ["rm -rf /"],
+  },
+}
+```
+
+### Extending the guard
+
+The guard source is at [`src/credential-guard/index.ts`](./src/credential-guard/index.ts). Fork the repo, adjust patterns, submit a PR: https://github.com/blogic-cz/agent-tools
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@blogic-cz/agent-tools",
+  "version": "0.1.0",
+  "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, and sessions",
+  "keywords": [
+    "agent",
+    "ai",
+    "cli",
+    "database",
+    "devops",
+    "github",
+    "kubernetes",
+    "tools"
+  ],
+  "homepage": "https://github.com/blogic-cz/agent-tools#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blogic-cz/agent-tools.git"
+  },
+  "bin": {
+    "agent-tools-az": "./src/az-tool/index.ts",
+    "agent-tools-db": "./src/db-tool/index.ts",
+    "agent-tools-gh": "./src/gh-tool/index.ts",
+    "agent-tools-k8s": "./src/k8s-tool/index.ts",
+    "agent-tools-logs": "./src/logs-tool/index.ts",
+    "agent-tools-session": "./src/session-tool/index.ts"
+  },
+  "files": [
+    "src/",
+    "schemas/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./credential-guard": "./src/credential-guard/index.ts",
+    "./config": "./src/config/index.ts"
+  },
+  "scripts": {
+    "check": "bun check.ts",
+    "check:ci": "bun check.ts ci",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint -c ./.oxlintrc.json --deny-warnings",
+    "lint:fix": "oxlint -c ./.oxlintrc.json --fix",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "4.0.0-beta.20",
+    "@toon-format/toon": "2.1.0",
+    "effect": "4.0.0-beta.20"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.77.0",
+    "@effect/vitest": "4.0.0-beta.20",
+    "@types/bun": "1.3.9",
+    "oxfmt": "0.35.0",
+    "oxlint": "1.50.0",
+    "typescript": "5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/schemas/agent-tools.schema.json

@@ -0,0 +1,319 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+  "title": "Agent Tools Configuration",
+  "description": "Root configuration for the agent-tools package. Tool-specific sections (azure, kubernetes, database, logs) are maps of named profiles keyed by profile name. Tools choose a profile via --profile <name> (default key is 'default', single-entry maps can be auto-selected). session and credentialGuard are global sections.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "description": "Optional self-reference URL to this JSON Schema.",
+      "type": "string"
+    },
+    "azure": {
+      "description": "Named Azure DevOps profiles as Record<string, AzureConfig>.",
+      "type": "object",
+      "additionalProperties": {
+        "description": "Azure DevOps profile configuration for a specific environment or project.",
+        "$ref": "#/definitions/AzureConfig"
+      }
+    },
+    "kubernetes": {
+      "description": "Named Kubernetes cluster profiles as Record<string, K8sConfig>.",
+      "type": "object",
+      "additionalProperties": {
+        "description": "Kubernetes cluster configuration for a specific environment.",
+        "$ref": "#/definitions/K8sConfig"
+      }
+    },
+    "database": {
+      "description": "Named database profiles as Record<string, DatabaseConfig>.",
+      "type": "object",
+      "additionalProperties": {
+        "description": "Database profile configuration containing one or more environments.",
+        "$ref": "#/definitions/DatabaseConfig"
+      }
+    },
+    "logs": {
+      "description": "Named logs profiles as Record<string, LogsConfig>.",
+      "type": "object",
+      "additionalProperties": {
+        "description": "Logs profile configuration for local and remote access.",
+        "$ref": "#/definitions/LogsConfig"
+      }
+    },
+    "session": {
+      "description": "Global session configuration shared across profiles.",
+      "$ref": "#/definitions/SessionConfig"
+    },
+    "credentialGuard": {
+      "description": "Global credential guard configuration merged with built-in defaults.",
+      "$ref": "#/definitions/CredentialGuardConfig"
+    }
+  },
+  "definitions": {
+    "AzureConfig": {
+      "description": "Azure DevOps profile configuration.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "organization": {
+          "description": "Azure DevOps organization URL or identifier.",
+          "type": "string"
+        },
+        "defaultProject": {
+          "description": "Default Azure DevOps project name.",
+          "type": "string"
+        },
+        "timeoutMs": {
+          "description": "Optional command timeout in milliseconds.",
+          "type": "number"
+        }
+      },
+      "required": ["organization", "defaultProject"]
+    },
+    "K8sConfig": {
+      "description": "Kubernetes cluster profile configuration.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "clusterId": {
+          "description": "Cluster identifier.",
+          "type": "string"
+        },
+        "namespaces": {
+          "description": "Named namespaces map, for example { \"test\": \"my-app-test\", \"prod\": \"my-app-prod\" }.",
+          "type": "object",
+          "additionalProperties": {
+            "description": "Kubernetes namespace value for the given key.",
+            "type": "string"
+          }
+        },
+        "timeoutMs": {
+          "description": "Optional command timeout in milliseconds.",
+          "type": "number"
+        }
+      },
+      "required": ["clusterId", "namespaces"]
+    },
+    "DbEnvConfig": {
+      "description": "Single database environment connection details.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "host": {
+          "description": "Database host name or address.",
+          "type": "string"
+        },
+        "port": {
+          "description": "Database port.",
+          "type": "number"
+        },
+        "user": {
+          "description": "Database user name.",
+          "type": "string"
+        },
+        "database": {
+          "description": "Database name.",
+          "type": "string"
+        },
+        "passwordEnvVar": {
+          "description": "Name of the environment variable holding the database password.",
+          "type": "string"
+        }
+      },
+      "required": ["host", "port", "user", "database"]
+    },
+    "DatabaseConfig": {
+      "description": "Database profile configuration.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "environments": {
+          "description": "Named database environments as Record<string, DbEnvConfig>.",
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/DbEnvConfig"
+          }
+        },
+        "kubectl": {
+          "description": "Optional kubectl tunnel settings.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "context": {
+              "description": "Kubectl context name.",
+              "type": "string"
+            },
+            "namespace": {
+              "description": "Kubectl namespace for tunnel commands.",
+              "type": "string"
+            }
+          },
+          "required": ["context", "namespace"]
+        },
+        "tunnelTimeoutMs": {
+          "description": "Optional timeout for establishing a tunnel, in milliseconds.",
+          "type": "number"
+        },
+        "remotePort": {
+          "description": "Optional remote database port used by the tunnel.",
+          "type": "number"
+        }
+      },
+      "required": ["environments"]
+    },
+    "LogsConfig": {
+      "description": "Logs profile configuration.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "localDir": {
+          "description": "Local logs directory path.",
+          "type": "string"
+        },
+        "remotePath": {
+          "description": "Remote logs path used in container or host environments.",
+          "type": "string"
+        }
+      },
+      "required": ["localDir", "remotePath"]
+    },
+    "SessionConfig": {
+      "description": "Global session configuration.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "storagePath": {
+          "description": "Filesystem path used for session storage.",
+          "type": "string"
+        }
+      },
+      "required": ["storagePath"]
+    },
+    "CliToolOverride": {
+      "description": "CLI override entry that blocks a tool and recommends a safer wrapper.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tool": {
+          "description": "CLI tool name to block.",
+          "type": "string"
+        },
+        "suggestion": {
+          "description": "Suggested wrapper command or alternative.",
+          "type": "string"
+        }
+      },
+      "required": ["tool", "suggestion"]
+    },
+    "CredentialGuardConfig": {
+      "description": "Credential guard additions merged with built-in defaults.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "additionalBlockedPaths": {
+          "description": "Additional blocked file path patterns.",
+          "type": "array",
+          "items": {
+            "description": "Blocked path pattern.",
+            "type": "string"
+          }
+        },
+        "additionalAllowedPaths": {
+          "description": "Additional allowed file path patterns.",
+          "type": "array",
+          "items": {
+            "description": "Allowed path pattern.",
+            "type": "string"
+          }
+        },
+        "additionalBlockedCliTools": {
+          "description": "Additional blocked CLI tools and recommendations.",
+          "type": "array",
+          "items": {
+            "description": "Blocked CLI tool override entry.",
+            "$ref": "#/definitions/CliToolOverride"
+          }
+        },
+        "additionalDangerousBashPatterns": {
+          "description": "Additional dangerous bash patterns to block.",
+          "type": "array",
+          "items": {
+            "description": "Dangerous bash pattern.",
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "$schema": "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+      "azure": {
+        "default": {
+          "organization": "https://dev.azure.com/example-org",
+          "defaultProject": "platform",
+          "timeoutMs": 60000
+        }
+      },
+      "kubernetes": {
+        "default": {
+          "clusterId": "398bf1ad-788c-40f5-a7e0-88366648d9d9",
+          "namespaces": {
+            "test": "my-app-test",
+            "prod": "my-app-prod",
+            "system": "bl-system"
+          },
+          "timeoutMs": 60000
+        }
+      },
+      "database": {
+        "default": {
+          "environments": {
+            "local": {
+              "host": "127.0.0.1",
+              "port": 25538,
+              "user": "my-app-user",
+              "database": "my-app",
+              "passwordEnvVar": "AGENT_TOOLS_DB_LOCAL_CRED"
+            },
+            "test": {
+              "host": "127.0.0.1",
+              "port": 25437,
+              "user": "readonly-user",
+              "database": "my-app-test",
+              "passwordEnvVar": "AGENT_TOOLS_DB_TEST_CRED"
+            }
+          },
+          "kubectl": {
+            "context": "cloud2-example-cz",
+            "namespace": "bl-system"
+          },
+          "tunnelTimeoutMs": 5000,
+          "remotePort": 5432
+        }
+      },
+      "logs": {
+        "default": {
+          "localDir": "apps/web-app/logs",
+          "remotePath": "/app/logs"
+        }
+      },
+      "session": {
+        "storagePath": "~/.local/share/opencode/storage"
+      },
+      "credentialGuard": {
+        "additionalBlockedPaths": ["private/"],
+        "additionalAllowedPaths": ["apps/web-app/.env.test"],
+        "additionalBlockedCliTools": [
+          {
+            "tool": "kubectl",
+            "suggestion": "Use bun run k8s-tool instead"
+          }
+        ],
+        "additionalDangerousBashPatterns": ["rm -rf /"]
+      }
+    }
+  ]
+}