@blogic-cz/agent-tools 0.1.0

package/src/az-tool/service.ts

@@ -0,0 +1,292 @@
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { Effect, Layer, ServiceMap, Stream, Option } from "effect";
+
+import type { InvokeParams } from "./types";
+import type { AzureConfig } from "../config/types";
+
+import { DIRECT_AZ_COMMANDS, STANDALONE_AZ_COMMANDS } from "./config";
+import { AzSecurityError, AzCommandError, AzTimeoutError, AzParseError } from "./errors";
+import { isCommandAllowed, isInvokeAllowed } from "./security";
+import { ConfigService, getToolConfig } from "../config";
+
+export class AzService extends ServiceMap.Service<
+  AzService,
+  {
+    readonly runCommand: (
+      cmd: string,
+      project?: string,
+    ) => Effect.Effect<string, AzSecurityError | AzCommandError | AzTimeoutError | AzParseError>;
+    readonly runInvoke: (
+      params: InvokeParams,
+    ) => Effect.Effect<unknown, AzSecurityError | AzCommandError | AzTimeoutError | AzParseError>;
+  }
+>()("@agent-tools/AzService") {
+  static readonly layer = Layer.effect(
+    AzService,
+    Effect.gen(function* () {
+      const config = yield* ConfigService;
+      const azConfig = getToolConfig<AzureConfig>(config, "azure");
+
+      if (!azConfig) {
+        const noConfigError = new AzCommandError({
+          message: "No Azure configuration found. Add an 'azure' section to agent-tools.json5.",
+          command: "unknown",
+          exitCode: -1,
+          stderr: undefined,
+        });
+        return {
+          runCommand: (_cmd: string, _project?: string) => Effect.fail(noConfigError),
+          runInvoke: (_params: InvokeParams) => Effect.fail(noConfigError),
+        };
+      }
+
+      const executor = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+      const runShellCommand = (fullCommand: string, timeoutMs: number) =>
+        Effect.scoped(
+          Effect.gen(function* () {
+            const command = ChildProcess.make("sh", ["-c", fullCommand], {
+              stdout: "pipe",
+              stderr: "pipe",
+            });
+            const process = yield* executor.spawn(command);
+
+            const stdoutChunk = yield* process.stdout.pipe(Stream.decodeText(), Stream.runCollect);
+            const stdout = stdoutChunk.join("");
+
+            const stderrChunk = yield* process.stderr.pipe(Stream.decodeText(), Stream.runCollect);
+            const stderr = stderrChunk.join("");
+
+            const exitCode = yield* process.exitCode;
+
+            return { stdout, stderr, exitCode };
+          }),
+        ).pipe(
+          Effect.timeoutOption(timeoutMs),
+          Effect.mapError(
+            (platformError) =>
+              new AzCommandError({
+                message: `Command execution failed: ${platformError.message}`,
+                command: fullCommand,
+                exitCode: -1,
+                stderr: undefined,
+              }),
+          ),
+        );
+
+      const resolveProject = (project?: string) => project ?? azConfig.defaultProject;
+
+      const runCommand = Effect.fn("AzService.runCommand")(function* (
+        cmd: string,
+        project?: string,
+      ) {
+        const projectName = resolveProject(project);
+
+        const securityCheck = isCommandAllowed(cmd);
+        if (!securityCheck.allowed) {
+          return yield* new AzSecurityError({
+            message: securityCheck.reason ?? "Command not allowed",
+            command: cmd,
+          });
+        }
+
+        const invokeParams = parseInvokeFromCommand(cmd);
+        if (invokeParams) {
+          const invokeResult = yield* runInvoke({
+            ...invokeParams,
+            project: projectName,
+          });
+          return JSON.stringify(invokeResult);
+        }
+
+        const cmdWords = cmd.trim().split(/\s+/);
+        const firstWord = cmdWords[0]?.toLowerCase() ?? "";
+        const isDirectCommand = DIRECT_AZ_COMMANDS.includes(
+          firstWord as (typeof DIRECT_AZ_COMMANDS)[number],
+        );
+        const isStandaloneCommand = STANDALONE_AZ_COMMANDS.includes(
+          firstWord as (typeof STANDALONE_AZ_COMMANDS)[number],
+        );
+
+        let fullCommand: string;
+
+        if (isStandaloneCommand) {
+          fullCommand = `az ${cmd}`;
+        } else if (isDirectCommand) {
+          fullCommand = `az ${cmd} --organization "${azConfig.organization}" --project "${projectName}"`;
+        } else {
+          fullCommand = `az devops ${cmd} --organization "${azConfig.organization}" --project "${projectName}"`;
+        }
+
+        const resultOption = yield* runShellCommand(fullCommand, azConfig.timeoutMs ?? 60000);
+
+        if (Option.isNone(resultOption)) {
+          return yield* new AzTimeoutError({
+            message: `Command timed out after ${azConfig.timeoutMs ?? 60000}ms`,
+            command: fullCommand,
+            timeoutMs: azConfig.timeoutMs ?? 60000,
+          });
+        }
+
+        const result = resultOption.value;
+
+        if (result.exitCode !== 0) {
+          return yield* new AzCommandError({
+            message: result.stderr || `Command failed with exit code ${result.exitCode}`,
+            command: fullCommand,
+            exitCode: result.exitCode,
+            stderr: result.stderr || undefined,
+          });
+        }
+
+        return result.stdout;
+      });
+
+      const runInvoke = Effect.fn("AzService.runInvoke")(function* (params: InvokeParams) {
+        const securityCheck = isInvokeAllowed(params);
+        if (!securityCheck.allowed) {
+          return yield* new AzSecurityError({
+            message: securityCheck.reason ?? "Invoke not allowed",
+            command: `invoke --area ${params.area} --resource ${params.resource}`,
+          });
+        }
+
+        let fullCommand = `az devops invoke --area ${params.area} --resource ${params.resource}`;
+
+        const projectName = resolveProject(params.project);
+
+        const routeParameters = {
+          project: projectName,
+          ...params.routeParameters,
+        };
+
+        if (Object.keys(routeParameters).length > 0) {
+          const routeParams = Object.entries(routeParameters)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(" ");
+          fullCommand += ` --route-parameters ${routeParams}`;
+        }
+
+        if (params.queryParameters) {
+          const queryParams = Object.entries(params.queryParameters)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(" ");
+          fullCommand += ` --query-parameters ${queryParams}`;
+        }
+
+        fullCommand += ` --organization "${azConfig.organization}" --output json`;
+
+        const resultOption = yield* runShellCommand(fullCommand, azConfig.timeoutMs ?? 60000);
+
+        if (Option.isNone(resultOption)) {
+          return yield* new AzTimeoutError({
+            message: `Invoke timed out after ${azConfig.timeoutMs ?? 60000}ms`,
+            command: fullCommand,
+            timeoutMs: azConfig.timeoutMs ?? 60000,
+          });
+        }
+
+        const result = resultOption.value;
+
+        if (result.exitCode !== 0) {
+          return yield* new AzCommandError({
+            message: result.stderr || `Invoke failed with exit code ${result.exitCode}`,
+            command: fullCommand,
+            exitCode: result.exitCode,
+            stderr: result.stderr || undefined,
+          });
+        }
+
+        const jsonData = yield* Effect.try({
+          try: () => JSON.parse(result.stdout) as unknown,
+          catch: () =>
+            new AzParseError({
+              message: `Failed to parse JSON response from invoke`,
+              rawOutput: result.stdout.slice(0, 500),
+            }),
+        });
+        return jsonData;
+      });
+
+      return { runCommand, runInvoke };
+    }),
+  );
+}
+
+export const AzServiceLayer = AzService.layer;
+
+function parseInvokeFromCommand(cmd: string): InvokeParams | undefined {
+  const words = cmd.trim().split(/\s+/);
+  const loweredWords = words.map((word) => word.toLowerCase());
+
+  if (!loweredWords.includes("invoke")) {
+    return undefined;
+  }
+
+  const area = extractOptionValue(words, "--area");
+  const resource = extractOptionValue(words, "--resource");
+
+  if (!area || !resource) {
+    return undefined;
+  }
+
+  const routeParameters = extractParametersOption(words, "--route-parameters");
+  const queryParameters = extractParametersOption(words, "--query-parameters");
+  const apiVersion = extractOptionValue(words, "--api-version");
+
+  const mergedQueryParameters = apiVersion
+    ? {
+        ...queryParameters,
+        "api-version": apiVersion,
+      }
+    : queryParameters;
+
+  return {
+    area,
+    resource,
+    ...(routeParameters ? { routeParameters } : {}),
+    ...(mergedQueryParameters ? { queryParameters: mergedQueryParameters } : {}),
+  };
+}
+
+function extractOptionValue(args: readonly string[], optionName: string): string | undefined {
+  const optionIndex = args.findIndex((arg) => arg.toLowerCase() === optionName.toLowerCase());
+
+  if (optionIndex === -1) {
+    return undefined;
+  }
+
+  return args[optionIndex + 1];
+}
+
+function extractParametersOption(
+  args: readonly string[],
+  optionName: string,
+): Record<string, string | number> | undefined {
+  const optionIndex = args.findIndex((arg) => arg.toLowerCase() === optionName.toLowerCase());
+
+  if (optionIndex === -1) {
+    return undefined;
+  }
+
+  const result: Record<string, string | number> = {};
+
+  for (let i = optionIndex + 1; i < args.length; i++) {
+    const token = args[i];
+    if (!token || token.startsWith("--")) {
+      break;
+    }
+
+    const equalsIndex = token.indexOf("=");
+    if (equalsIndex === -1) {
+      continue;
+    }
+
+    const key = token.slice(0, equalsIndex);
+    const rawValue = token.slice(equalsIndex + 1);
+    const parsedNumber = Number(rawValue);
+    result[key] = Number.isNaN(parsedNumber) ? rawValue : parsedNumber;
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}

package/src/az-tool/types.ts

@@ -0,0 +1,67 @@
+export type SecurityCheckResult = {
+  allowed: boolean;
+  command?: string;
+  reason?: string;
+};
+
+export type InvokeParams = {
+  area: string;
+  resource: string;
+  project?: string;
+  routeParameters?: Record<string, string | number>;
+  queryParameters?: Record<string, string | number>;
+};
+
+export type BuildJob = {
+  id: string;
+  parentId?: string | null;
+  type: "Job" | "Stage" | "Task" | "Phase" | "Checkpoint";
+  name: string;
+  state: "pending" | "inProgress" | "completed";
+  result?: "succeeded" | "failed" | "canceled" | "skipped" | null;
+  startTime?: string | null;
+  finishTime?: string | null;
+  errorCount?: number | null;
+  warningCount?: number | null;
+  log?: { id: number; url: string } | null;
+};
+
+export type BuildTimeline = {
+  records: BuildJob[];
+  id: string;
+  changeId: number;
+  lastChangedBy: string;
+  lastChangedOn: string;
+  url: string;
+};
+
+export type BuildLog = {
+  id: number;
+  type: string;
+  url: string;
+  lineCount?: number;
+};
+
+export type BuildLogs = {
+  count: number;
+  value: BuildLog[];
+};
+
+export type JobSummary = {
+  name: string;
+  state: string;
+  result?: string;
+  stage?: string;
+  duration?: string;
+  logId?: number;
+};
+
+export type PipelineRun = {
+  id: number;
+  buildNumber: string;
+  status: string;
+  result?: string;
+  sourceBranch: string;
+  startTime?: string;
+  finishTime?: string;
+};

package/src/config/index.ts

@@ -0,0 +1,12 @@
+export type {
+  AgentToolsConfig,
+  AzureConfig,
+  K8sConfig,
+  DbEnvConfig,
+  DatabaseConfig,
+  LogsConfig,
+  CliToolOverride,
+  CredentialGuardConfig,
+} from "./types.ts";
+
+export { ConfigService, ConfigServiceLayer, getToolConfig, loadConfig } from "./loader";

package/src/config/loader.ts

@@ -0,0 +1,170 @@
+import { dirname } from "node:path";
+
+import { Data, Effect, Layer, Schema, ServiceMap } from "effect";
+
+import type { AgentToolsConfig } from "./types.ts";
+
+const CliToolOverrideSchema = Schema.Struct({
+  tool: Schema.String,
+  suggestion: Schema.String,
+});
+
+const CredentialGuardConfigSchema = Schema.Struct({
+  additionalBlockedPaths: Schema.optionalKey(Schema.Array(Schema.String)),
+  additionalAllowedPaths: Schema.optionalKey(Schema.Array(Schema.String)),
+  additionalBlockedCliTools: Schema.optionalKey(Schema.Array(CliToolOverrideSchema)),
+  additionalDangerousBashPatterns: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+const AzureConfigSchema = Schema.Struct({
+  organization: Schema.String,
+  defaultProject: Schema.String,
+  timeoutMs: Schema.optionalKey(Schema.Number),
+});
+
+const K8sConfigSchema = Schema.Struct({
+  clusterId: Schema.String,
+  namespaces: Schema.Record(Schema.String, Schema.String),
+  timeoutMs: Schema.optionalKey(Schema.Number),
+});
+
+const DbEnvConfigSchema = Schema.Struct({
+  host: Schema.String,
+  port: Schema.Number,
+  user: Schema.String,
+  database: Schema.String,
+  passwordEnvVar: Schema.optionalKey(Schema.String),
+});
+
+const DatabaseConfigSchema = Schema.Struct({
+  environments: Schema.Record(Schema.String, DbEnvConfigSchema),
+  kubectl: Schema.optionalKey(
+    Schema.Struct({
+      context: Schema.String,
+      namespace: Schema.String,
+    }),
+  ),
+  tunnelTimeoutMs: Schema.optionalKey(Schema.Number),
+  remotePort: Schema.optionalKey(Schema.Number),
+});
+
+const LogsConfigSchema = Schema.Struct({
+  localDir: Schema.String,
+  remotePath: Schema.String,
+});
+
+const AgentToolsConfigSchema = Schema.Struct({
+  $schema: Schema.optionalKey(Schema.String),
+  azure: Schema.optionalKey(Schema.Record(Schema.String, AzureConfigSchema)),
+  kubernetes: Schema.optionalKey(Schema.Record(Schema.String, K8sConfigSchema)),
+  database: Schema.optionalKey(Schema.Record(Schema.String, DatabaseConfigSchema)),
+  logs: Schema.optionalKey(Schema.Record(Schema.String, LogsConfigSchema)),
+  session: Schema.optionalKey(
+    Schema.Struct({
+      storagePath: Schema.String,
+    }),
+  ),
+  credentialGuard: Schema.optionalKey(CredentialGuardConfigSchema),
+});
+
+async function findConfigFile(startDirectory: string = process.cwd()): Promise<string | undefined> {
+  let currentDirectory = startDirectory;
+
+  while (true) {
+    const json5Path = `${currentDirectory}/agent-tools.json5`;
+    if (await Bun.file(json5Path).exists()) {
+      return json5Path;
+    }
+
+    const jsonPath = `${currentDirectory}/agent-tools.json`;
+    if (await Bun.file(jsonPath).exists()) {
+      return jsonPath;
+    }
+
+    const parentDirectory = dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return undefined;
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+
+export async function loadConfig(): Promise<AgentToolsConfig | undefined> {
+  const configPath = await findConfigFile();
+  if (!configPath) {
+    return undefined;
+  }
+
+  const fileContent = await Bun.file(configPath).text();
+  const parsed = Bun.JSON5.parse(fileContent);
+
+  try {
+    const decoded = Schema.decodeUnknownSync(AgentToolsConfigSchema)(parsed);
+    return decoded as AgentToolsConfig;
+  } catch (error) {
+    throw new Error(
+      `Invalid agent-tools config at ${configPath}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+export class ConfigService extends ServiceMap.Service<
+  ConfigService,
+  AgentToolsConfig | undefined
+>()("@agent-tools/ConfigService") {}
+
+export class ConfigLoadError extends Data.TaggedError("ConfigLoadError")<{
+  readonly cause: unknown;
+}> {}
+
+export const ConfigServiceLayer = Layer.effect(
+  ConfigService,
+  Effect.tryPromise({
+    try: () => loadConfig(),
+    catch: (error) => new ConfigLoadError({ cause: error }),
+  }),
+);
+
+type ProfiledSection = keyof Pick<AgentToolsConfig, "azure" | "kubernetes" | "database" | "logs">;
+
+export function getToolConfig<T>(
+  config: AgentToolsConfig | undefined,
+  section: ProfiledSection,
+  profile?: string,
+): T | undefined {
+  if (!config) {
+    return undefined;
+  }
+
+  const sectionData = config[section] as Record<string, T> | undefined;
+  if (!sectionData) {
+    return undefined;
+  }
+
+  const keys = Object.keys(sectionData);
+  if (keys.length === 0) {
+    return undefined;
+  }
+
+  if (profile) {
+    return sectionData[profile];
+  }
+
+  if (keys.length === 1) {
+    const onlyKey = keys[0];
+    if (!onlyKey) {
+      return undefined;
+    }
+    return sectionData[onlyKey];
+  }
+
+  if ("default" in sectionData) {
+    return sectionData.default;
+  }
+
+  throw new Error(
+    `Multiple ${section} profiles found: [${keys.join(", ")}]. Use --profile <name> to select one.`,
+  );
+}

package/src/config/types.ts

@@ -0,0 +1,82 @@
+/** Azure DevOps profile configuration */
+export type AzureConfig = {
+  organization: string;
+  defaultProject: string;
+  timeoutMs?: number;
+};
+
+/** Kubernetes cluster profile configuration */
+export type K8sConfig = {
+  clusterId: string;
+  /** Named namespaces, e.g. { test: "my-app-test", prod: "my-app-prod" } */
+  namespaces: Record<string, string>;
+  timeoutMs?: number;
+};
+
+/** Single database environment connection details */
+export type DbEnvConfig = {
+  host: string;
+  port: number;
+  user: string;
+  database: string;
+  /** Name of environment variable holding the password, e.g. "DB_TEST_PWD" */
+  passwordEnvVar?: string;
+};
+
+/** Database profile configuration */
+export type DatabaseConfig = {
+  /** Named database environments, e.g. { local: {...}, test: {...}, prod: {...} } */
+  environments: Record<string, DbEnvConfig>;
+  kubectl?: {
+    context: string;
+    namespace: string;
+  };
+  tunnelTimeoutMs?: number;
+  remotePort?: number;
+};
+
+/** Logs profile configuration */
+export type LogsConfig = {
+  localDir: string;
+  remotePath: string;
+};
+
+export type CliToolOverride = {
+  tool: string;
+  suggestion: string;
+};
+
+/** Credential guard config - merged with built-in defaults */
+export type CredentialGuardConfig = {
+  additionalBlockedPaths?: string[];
+  additionalAllowedPaths?: string[];
+  additionalBlockedCliTools?: CliToolOverride[];
+  additionalDangerousBashPatterns?: string[];
+};
+
+/**
+ * Root agent-tools configuration.
+ *
+ * Each tool section (azure, kubernetes, database, logs) is a Record<string, ToolConfig>
+ * of named profiles. Tools select a profile via the --profile <name> flag (default = "default" key).
+ * If only one profile exists, it is used automatically.
+ *
+ * session and credentialGuard are global - not per-profile.
+ */
+export type AgentToolsConfig = {
+  $schema?: string;
+  /** Named Azure DevOps profiles. e.g. { default: { organization: "...", defaultProject: "..." } } */
+  azure?: Record<string, AzureConfig>;
+  /** Named Kubernetes cluster profiles. e.g. { default: {...}, staging: {...} } */
+  kubernetes?: Record<string, K8sConfig>;
+  /** Named database profiles. e.g. { default: {...}, analytics: {...} } */
+  database?: Record<string, DatabaseConfig>;
+  /** Named logs profiles. e.g. { default: { localDir: "...", remotePath: "..." } } */
+  logs?: Record<string, LogsConfig>;
+  /** Global session config (not per-profile) */
+  session?: {
+    storagePath: string;
+  };
+  /** Global credential guard config (merged with built-in defaults, not per-profile) */
+  credentialGuard?: CredentialGuardConfig;
+};

package/src/credential-guard/claude-hook.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+/**
+ * Claude Code PreToolUse hook wrapper.
+ *
+ * Reads JSON from stdin (Claude Code hook protocol), runs the credential guard,
+ * and exits with code 2 + stderr message if blocked, or 0 if allowed.
+ *
+ * Usage in .claude/settings.json:
+ *   { "hooks": { "PreToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command",
+ *     "command": "bun node_modules/@blogic-cz/agent-tools/src/credential-guard/claude-hook.ts" }] }] } }
+ */
+
+import { handleToolExecuteBefore } from "./index";
+
+const stdin = await Bun.stdin.text();
+
+try {
+  const data: {
+    tool_name: string;
+    tool_input?: Record<string, unknown>;
+  } = JSON.parse(stdin);
+
+  handleToolExecuteBefore({ tool: data.tool_name }, { args: data.tool_input ?? {} });
+} catch (error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(message);
+  process.exit(2);
+}