@blogic-cz/agent-tools 0.14.6 → 0.14.9

package/README.md

@@ -178,6 +178,8 @@ bun run agent-tools/example-tool/index.ts ping
       // auto defaults to true:
       // darwin -> macos-scutil, linux -> linux-nmcli, win32 -> windows-rasdial
       name: "ExampleVPN",
+      // Optional: pass IPSec shared secret to macOS scutil from env without storing the value in config.
+      secretEnvVar: "EXAMPLE_VPN_IPSEC_SHARED_SECRET",
     },
   },
   kubernetes: {

package/package.json

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

@@ -428,6 +428,10 @@
         },
         "serviceName": {
           "type": "string"
+        },
+        "secretEnvVar": {
+          "type": "string",
+          "description": "Name of environment variable holding the IPSec shared secret for scutil --nc start."
         }
       },
       "required": ["type"]
@@ -502,6 +506,10 @@
         "leaseTtlMs": {
           "type": "number"
         },
+        "secretEnvVar": {
+          "type": "string",
+          "description": "Name of environment variable holding the VPN shared secret for supported drivers."
+        },
         "drivers": {
           "type": "object",
           "additionalProperties": false,

package/src/config/loader.ts

@@ -30,6 +30,7 @@ const PrerequisitesSchema = Schema.Array(PrerequisiteSchema);
 const MacosScutilVpnDriverConfigSchema = Schema.Struct({
   type: Schema.Literal("macos-scutil"),
   serviceName: Schema.optionalKey(Schema.String),
+  secretEnvVar: Schema.optionalKey(Schema.String),
 });
 
 const LinuxNmcliVpnDriverConfigSchema = Schema.Struct({
@@ -56,6 +57,7 @@ const VpnConfigSchema = Schema.Struct({
   disconnectTimeoutMs: Schema.optionalKey(Schema.Number),
   cooldownMs: Schema.optionalKey(Schema.Number),
   leaseTtlMs: Schema.optionalKey(Schema.Number),
+  secretEnvVar: Schema.optionalKey(Schema.String),
   drivers: Schema.optionalKey(
     Schema.Struct({
       darwin: Schema.optionalKey(MacosScutilVpnDriverConfigSchema),

package/src/config/types.ts

@@ -16,6 +16,8 @@ export type VpnPrerequisite = {
 export type MacosScutilVpnDriverConfig = {
   type: "macos-scutil";
   serviceName?: string;
+  /** Name of environment variable holding the IPSec shared secret for scutil --nc start. */
+  secretEnvVar?: string;
 };
 
 export type LinuxNmcliVpnDriverConfig = {
@@ -42,6 +44,8 @@ export type VpnConfig = {
   disconnectTimeoutMs?: number;
   cooldownMs?: number;
   leaseTtlMs?: number;
+  /** Name of environment variable holding the VPN shared secret for supported drivers. */
+  secretEnvVar?: string;
   drivers?: {
     darwin?: MacosScutilVpnDriverConfig;
     linux?: LinuxNmcliVpnDriverConfig;

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,153 @@
+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";
+
+type LogLine = {
+  readonly timestamp: string;
+  readonly line: string;
+  readonly labels: Record<string, string>;
+};
+
+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 {};
+  }
+}
+
+export function extractLogsFromDsQuery(response: {
+  results: {
+    A: {
+      frames?: Array<{
+        schema: { fields: Array<{ name: string; type?: 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" || 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]) : {},
+      });
+    }
+  }
+
+  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.catch((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/shared/prerequisites/runtime.ts

@@ -8,18 +8,25 @@ import { normalizeProfilePrerequisites } from "#shared/prerequisites/config";
 import { PrerequisiteRunError } from "#shared/prerequisites/errors";
 import { missingVpnToolHint, resolveVpnDriverConfig } from "#shared/prerequisites/vpn";
 
+const readEnv = (name: string) => Bun.env[name];
+
 const makeVpnCommand = (driver: ResolvedVpnDriver, action: "status" | "start" | "stop") => {
   if (driver.type === "macos-scutil") {
+    const secret = driver.secretEnvVar ? readEnv(driver.secretEnvVar) : undefined;
+    const secretArgs = action === "start" && secret ? ["--secret", secret] : [];
+    const redactedSecretArgs = secretArgs.length > 0 ? ["--secret", "<redacted>"] : [];
     const args =
       action === "status"
         ? ["--nc", "status", driver.serviceName]
         : action === "start"
-          ? ["--nc", "start", driver.serviceName]
+          ? ["--nc", "start", driver.serviceName, ...secretArgs]
           : ["--nc", "stop", driver.serviceName];
+    const labelArgs =
+      action === "start" ? ["--nc", "start", driver.serviceName, ...redactedSecretArgs] : args;
 
     return {
       command: ChildProcess.make("scutil", args, { stdout: "pipe", stderr: "pipe" }),
-      label: ["scutil", ...args].join(" "),
+      label: ["scutil", ...labelArgs].join(" "),
     };
   }
 
@@ -163,6 +170,17 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
           continue;
         }
 
+        if (
+          driver.type === "macos-scutil" &&
+          driver.secretEnvVar &&
+          !readEnv(driver.secretEnvVar)
+        ) {
+          return yield* new PrerequisiteRunError({
+            message: `VPN secret environment variable "${driver.secretEnvVar}" is not set.`,
+            hint: `Set ${driver.secretEnvVar} before running this tool or remove secretEnvVar from the VPN config.`,
+          });
+        }
+
         const startCommand = makeVpnCommand(driver, "start");
         const startResult = yield* runCommand(startCommand.command, startCommand.label).pipe(
           Effect.mapError(

package/src/shared/prerequisites/types.ts

@@ -15,9 +15,9 @@ export type PrerequisiteResolution =
 export type SupportedPlatform = "darwin" | "linux" | "win32";
 
 export type ResolvedVpnDriver =
-  | (Required<MacosScutilVpnDriverConfig> & { platform: "darwin" })
-  | (Required<LinuxNmcliVpnDriverConfig> & { platform: "linux" })
-  | (Required<WindowsRasdialVpnDriverConfig> & { platform: "win32" });
+  | (MacosScutilVpnDriverConfig & { platform: "darwin"; serviceName: string })
+  | (LinuxNmcliVpnDriverConfig & { platform: "linux"; connectionName: string })
+  | (WindowsRasdialVpnDriverConfig & { platform: "win32"; entryName: string });
 
 export type VpnDriverResolution =
   | { success: true; driver: ResolvedVpnDriver }

package/src/shared/prerequisites/vpn.ts

@@ -24,7 +24,12 @@ const resolveExplicitDriver = (
 
     return {
       success: true,
-      driver: { platform, type: driver.type, serviceName: driver.serviceName ?? config.name },
+      driver: {
+        platform,
+        type: driver.type,
+        serviceName: driver.serviceName ?? config.name,
+        secretEnvVar: driver.secretEnvVar ?? config.secretEnvVar,
+      },
     };
   }
 
@@ -93,7 +98,15 @@ export function resolveVpnDriverConfig(
   }
 
   if (platform === "darwin") {
-    return { success: true, driver: { platform, type: "macos-scutil", serviceName: config.name } };
+    return {
+      success: true,
+      driver: {
+        platform,
+        type: "macos-scutil",
+        serviceName: config.name,
+        secretEnvVar: config.secretEnvVar,
+      },
+    };
   }
 
   if (platform === "linux") {