@blogic-cz/agent-tools 0.14.11 → 0.14.13

package/package.json

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

package/src/config/loader.ts

@@ -75,6 +75,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),
@@ -95,6 +96,7 @@ const DatabaseConfigSchema = Schema.Struct({
   environments: Schema.Record(Schema.String, DbEnvConfigSchema),
   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

@@ -63,6 +63,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>;
@@ -86,6 +88,8 @@ export type DatabaseConfig = ProfilePrerequisites & {
   /** Named database environments, e.g. { local: {...}, test: {...}, prod: {...} } */
   environments: Record<string, DbEnvConfig>;
   kubectl?: {
+    /** Optional kubeconfig path. Supports ${ENV_VAR} templates. */
+    kubeconfig?: string;
     context: string;
     namespace: string;
     service?: string;

package/src/db-tool/service.ts

@@ -5,6 +5,7 @@ import type { DbConfig, 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 {
@@ -75,6 +76,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 +264,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 +294,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,

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/observability-tool/index.ts

@@ -10,6 +10,7 @@ import { AuditServiceLayer, withAudit } from "#shared/audit";
 import { VERSION } from "#shared";
 
 import { metricsCommand } from "./metrics";
+import { logsCommand } from "./logs";
 import { traceCommand } from "./trace";
 
 const renderCauseToStderr = (cause: Cause.Cause<unknown>) => Console.error(cause.toString());
@@ -18,7 +19,7 @@ const mainCommand = Command.make("observability-tool", {}).pipe(
   Command.withDescription(
     "LGTM observability queries — Tempo traces, Loki logs, Prometheus metrics",
   ),
-  Command.withSubcommands([traceCommand, metricsCommand]),
+  Command.withSubcommands([traceCommand, metricsCommand, logsCommand]),
 );
 
 const cli = Command.run(mainCommand, { version: VERSION });

package/src/observability-tool/logs.ts

@@ -0,0 +1,181 @@
+import { Console, Effect } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { formatOption, formatOutput } from "#shared";
+
+import { ObservabilityToolError } from "./errors";
+import {
+  envOption,
+  formatObservabilityError,
+  observabilityDsQuery,
+  profileOption,
+  resolveConfig,
+} from "./shared";
+
+import type { LogLine, StructuredLogLine } from "./types";
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value).every((item) => typeof item === "string")
+  );
+}
+
+function parseLabel(value: string | Record<string, string>): Record<string, string> {
+  if (isStringRecord(value)) {
+    return value;
+  }
+
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return isStringRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function parseStructuredLogLine(line: string): StructuredLogLine {
+  try {
+    const parsed = JSON.parse(line) as unknown;
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
+    }
+
+    const record = parsed as Record<string, unknown>;
+    return {
+      body: typeof record.body === "string" ? record.body : undefined,
+      severity: typeof record.severity === "string" ? record.severity : undefined,
+      attributes:
+        typeof record.attributes === "object" && record.attributes !== null
+          ? (record.attributes as Record<string, unknown>)
+          : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function extractLogsFromDsQuery(response: {
+  results: {
+    A: {
+      frames?: Array<{
+        schema: { fields: Array<{ name: string; type?: string; labels?: Record<string, string> }> };
+        data: { values: unknown[][] };
+      }>;
+    };
+  };
+}): LogLine[] {
+  const logs: LogLine[] = [];
+
+  for (const frame of response.results.A.frames ?? []) {
+    const fields = frame.schema.fields;
+    const values = frame.data.values;
+    const timeIndex = fields.findIndex(
+      (field) => field.name === "timestamp" || field.name === "Time" || field.type === "time",
+    );
+    const lineIndex = fields.findIndex(
+      (field) => field.name === "body" || field.name === "Line" || field.name === "line",
+    );
+    const labelsIndex = fields.findIndex((field) => field.name === "labels");
+
+    const timestamps = (timeIndex >= 0 ? values[timeIndex] : []) as Array<string | number>;
+    const lines = (lineIndex >= 0 ? values[lineIndex] : []) as string[];
+    const labelValues = (labelsIndex >= 0 ? values[labelsIndex] : []) as Array<
+      string | Record<string, string>
+    >;
+    const streamLabels = lineIndex >= 0 ? fields[lineIndex]?.labels : undefined;
+
+    for (const [index, line] of lines.entries()) {
+      const structured = parseStructuredLogLine(line);
+      logs.push({
+        timestamp: String(timestamps[index] ?? ""),
+        line,
+        ...structured,
+        labels: labelValues[index] ? parseLabel(labelValues[index]) : (streamLabels ?? {}),
+      });
+    }
+  }
+
+  return logs;
+}
+
+const queryCommand = Command.make(
+  "query",
+  {
+    logql: Argument.string("logql"),
+    format: formatOption,
+    env: envOption,
+    profile: profileOption,
+    start: Flag.string("start").pipe(
+      Flag.withDescription("Start time (default: now-1h)"),
+      Flag.withDefault("now-1h"),
+    ),
+    end: Flag.string("end").pipe(
+      Flag.withDescription("End time (default: now)"),
+      Flag.withDefault("now"),
+    ),
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Max log lines (default: 100)"),
+      Flag.withDefault(100),
+    ),
+  },
+  ({ logql, format, env, profile, start, end, limit }) => {
+    const startedAt = Date.now();
+
+    return Effect.gen(function* () {
+      const config = yield* resolveConfig(env, profile);
+      const response = yield* observabilityDsQuery(config, config.lokiUid, "loki", logql, {
+        from: start,
+        to: end,
+        maxLines: limit,
+      });
+
+      if (response.results.A.error) {
+        return yield* new ObservabilityToolError({ cause: new Error(response.results.A.error) });
+      }
+
+      const logs = extractLogsFromDsQuery(response).toSorted((left, right) =>
+        right.timestamp.localeCompare(left.timestamp),
+      );
+
+      const result = {
+        success: true,
+        message: `Found ${logs.length} Loki log line(s)`,
+        data: {
+          environment: env,
+          grafanaUrl: config.url,
+          lokiDatasourceUid: config.lokiUid,
+          query: logql,
+          start,
+          end,
+          limit,
+          logCount: logs.length,
+          logs,
+        },
+        executionTimeMs: Date.now() - startedAt,
+      };
+
+      yield* Console.log(formatOutput(result, format));
+    }).pipe(
+      Effect.catchTag("ObservabilityToolError", (error) =>
+        Effect.gen(function* () {
+          const result = {
+            success: false,
+            message: "Failed to execute LogQL query",
+            error: formatObservabilityError(error),
+            hint: "Check LogQL syntax and Grafana/Loki connectivity",
+            executionTimeMs: Date.now() - startedAt,
+          };
+          yield* Console.log(formatOutput(result, format));
+        }),
+      ),
+    );
+  },
+).pipe(Command.withDescription("Execute LogQL range query via Grafana/Loki"));
+
+export const logsCommand = Command.make("logs", {}).pipe(
+  Command.withDescription("Loki log operations via Grafana"),
+  Command.withSubcommands([queryCommand]),
+);

package/src/observability-tool/trace.ts

@@ -13,6 +13,7 @@ import {
   profileOption,
   resolveConfig,
 } from "./shared";
+import { extractLogsFromDsQuery } from "./logs";
 import type {
   FlattenedSpan,
   ObservabilityEnvConfig,
@@ -221,18 +222,6 @@ function summarizeTrace(traceId: string, spans: readonly FlattenedSpan[]): Trace
   };
 }
 
-function parseLabel(value: string | Record<string, string>): Record<string, string> {
-  if (typeof value === "object" && value !== null) {
-    return value;
-  }
-
-  try {
-    return JSON.parse(value) as Record<string, string>;
-  } catch {
-    return {};
-  }
-}
-
 type ResolvedTrace = {
   readonly resolution: SpanResolution;
   readonly spans: FlattenedSpan[];
@@ -482,34 +471,7 @@ const logsCommand = Command.make(
         });
       }
 
-      const logs: Array<{ timestamp: string; line: string; labels: Record<string, string> }> = [];
-      for (const frame of response.results.A.frames ?? []) {
-        const fields = frame.schema.fields;
-        const values = frame.data.values;
-        const timeIndex = fields.findIndex(
-          (field) => field.name === "timestamp" || field.type === "time",
-        );
-        const lineIndex = fields.findIndex(
-          (field) => field.name === "body" || field.name === "Line" || field.name === "line",
-        );
-        const labelsIndex = fields.findIndex(
-          (field) => field.name === "labels" || field.name === "labelTypes",
-        );
-
-        const timestamps = (timeIndex >= 0 ? values[timeIndex] : []) as Array<string | number>;
-        const lines = (lineIndex >= 0 ? values[lineIndex] : []) as string[];
-        const labelValues = (labelsIndex >= 0 ? values[labelsIndex] : []) as Array<
-          string | Record<string, string>
-        >;
-
-        for (const [index, line] of lines.entries()) {
-          logs.push({
-            timestamp: String(timestamps[index] ?? ""),
-            line,
-            labels: labelValues[index] ? parseLabel(labelValues[index]) : {},
-          });
-        }
-      }
+      const logs = extractLogsFromDsQuery(response);
 
       const result = {
         success: true,

package/src/observability-tool/types.ts

@@ -8,6 +8,21 @@ export type ObservabilityEnvConfig = {
   tempoUid: string;
 };
 
+export type LogLine = {
+  readonly timestamp: string;
+  readonly line: string;
+  readonly body?: string;
+  readonly severity?: string;
+  readonly attributes?: Record<string, unknown>;
+  readonly labels: Record<string, string>;
+};
+
+export type StructuredLogLine = {
+  readonly body?: string;
+  readonly severity?: string;
+  readonly attributes?: Record<string, unknown>;
+};
+
 export type GrafanaDatasource = {
   uid: string;
   name: string;

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("'", "'\\''")}'`;