@blogic-cz/agent-tools 0.14.1 → 0.14.3

package/README.md

@@ -174,17 +174,17 @@ bun run agent-tools/example-tool/index.ts ping
     dbPath: "~/.agent-tools/audit.sqlite",
   },
   vpns: {
-    blogic: {
+    exampleVpn: {
       // auto defaults to true:
       // darwin -> macos-scutil, linux -> linux-nmcli, win32 -> windows-rasdial
-      name: "BLVPN",
+      name: "ExampleVPN",
     },
   },
   kubernetes: {
     default: {
       clusterId: "your-cluster-id",
       namespaces: { test: "your-ns-test", prod: "your-ns-prod" },
-      prerequisites: [{ type: "vpn", key: "blogic" }],
+      prerequisites: [{ type: "vpn", key: "exampleVpn" }],
       // Prerequisites are currently decoded and validated as config metadata;
       // automatic VPN connect/disconnect execution is planned for a follow-up release.
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",
@@ -133,13 +133,13 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@effect/platform-bun": "4.0.0-beta.48",
+    "@effect/platform-bun": "4.0.0-beta.65",
     "@toon-format/toon": "2.1.0",
-    "effect": "4.0.0-beta.48"
+    "effect": "4.0.0-beta.65"
   },
   "devDependencies": {
     "@effect/language-service": "0.85.1",
-    "@effect/vitest": "4.0.0-beta.48",
+    "@effect/vitest": "4.0.0-beta.65",
     "@types/bun": "1.3.12",
     "oxfmt": "0.44.0",
     "oxlint": "1.59.0",
@@ -147,7 +147,7 @@
     "vitest": "^4.1.4"
   },
   "overrides": {
-    "@effect/platform-node-shared": "4.0.0-beta.48"
+    "@effect/platform-node-shared": "4.0.0-beta.65"
   },
   "engines": {
     "bun": ">=1.0.0"

package/schemas/agent-tools.schema.json

@@ -224,6 +224,17 @@
         "remotePort": {
           "description": "Optional remote database port used by the tunnel.",
           "type": "number"
+        },
+        "prerequisites": {
+          "description": "Ordered prerequisite references required before remote database access.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Prerequisite"
+          }
+        },
+        "vpn": {
+          "type": "string",
+          "description": "Convenience sugar for a VPN prerequisite key. Runtime normalizes this to prerequisites."
         }
       },
       "required": ["environments"]
@@ -529,7 +540,7 @@
           "namespaces": {
             "test": "my-app-test",
             "prod": "my-app-prod",
-            "system": "bl-system"
+            "system": "system"
           },
           "timeoutMs": 60000
         }
@@ -553,8 +564,8 @@
             }
           },
           "kubectl": {
-            "context": "cloud2-example-cz",
-            "namespace": "bl-system"
+            "context": "example-cluster",
+            "namespace": "system"
           },
           "tunnelTimeoutMs": 5000,
           "remotePort": 5432

package/src/config/loader.ts

@@ -100,6 +100,8 @@ const DatabaseConfigSchema = Schema.Struct({
   ),
   tunnelTimeoutMs: Schema.optionalKey(Schema.Number),
   remotePort: Schema.optionalKey(Schema.Number),
+  prerequisites: Schema.optionalKey(PrerequisitesSchema),
+  vpn: Schema.optionalKey(Schema.String),
 });
 
 const LogsConfigSchema = Schema.Struct({

package/src/config/types.ts

@@ -78,7 +78,7 @@ export type DbEnvConfig = {
 };
 
 /** Database profile configuration */
-export type DatabaseConfig = {
+export type DatabaseConfig = ProfilePrerequisites & {
   /** Named database environments, e.g. { local: {...}, test: {...}, prod: {...} } */
   environments: Record<string, DbEnvConfig>;
   kubectl?: {

package/src/db-tool/service.ts

@@ -3,6 +3,9 @@ import { Clock, Context, Duration, Effect, Layer, Ref, Stream } from "effect";
 
 import type { DbConfig, QueryResult, SchemaMode } from "./types";
 
+import { ConfigService } from "#config";
+import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
+import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
 import { DbConfigService, DbConfigServiceLayer, TUNNEL_CHECK_INTERVAL_MS } from "./config-service";
 import {
   DbConnectionError,
@@ -49,6 +52,7 @@ export class DbService extends Context.Service<
     Effect.scoped(
       Effect.gen(function* () {
         const executor = yield* ChildProcessSpawner.ChildProcessSpawner;
+        const agentToolsConfig = yield* ConfigService;
         const dbConfig = yield* DbConfigService;
 
         if (!dbConfig) {
@@ -170,6 +174,27 @@ export class DbService extends Context.Service<
             }),
           );
 
+        const runWithVpnPrerequisites = <E>(
+          port: number,
+          effect: Effect.Effect<QueryResult, E>,
+        ): Effect.Effect<QueryResult, E | DbTunnelError> =>
+          runWithProfilePrerequisites(
+            agentToolsConfig ?? {},
+            dbConfig,
+            (command, _label) => executeShellCommand(command),
+            effect,
+          ).pipe(
+            Effect.mapError((error) =>
+              isPrerequisiteRunError(error)
+                ? new DbTunnelError({
+                    message: error.message,
+                    port,
+                    hint: error.hint,
+                  })
+                : error,
+            ),
+          );
+
         const waitForPort = (port: number, timeoutMs: number, intervalMs: number) =>
           Effect.gen(function* () {
             const startTime = yield* Clock.currentTimeMillis;
@@ -573,7 +598,10 @@ export class DbService extends Context.Service<
             ? executeMutationQuery(config, sql, password, Number(startTimeMs))
             : executeSelectQuery(config, sql, password, Number(startTimeMs), true);
 
-          return yield* runQueryWithOptionalTunnel(config, queryEffect);
+          return yield* runWithVpnPrerequisites(
+            config.port,
+            runQueryWithOptionalTunnel(config, queryEffect),
+          );
         });
 
         const executeSchemaQuery = Effect.fn("DbService.executeSchemaQuery")(function* (
@@ -615,7 +643,10 @@ export class DbService extends Context.Service<
                   ? executeSelectQuery(config, getRelationships(), password, Number(startTimeMs))
                   : executeFullSchemaQuery(config, password, Number(startTimeMs));
 
-          const result = yield* runQueryWithOptionalTunnel(config, queryEffect);
+          const result = yield* runWithVpnPrerequisites(
+            config.port,
+            runQueryWithOptionalTunnel(config, queryEffect),
+          );
 
           if (result.success) {
             const descriptor =

package/src/k8s-tool/service.ts

@@ -11,6 +11,9 @@ import {
 } from "./errors";
 import { ConfigService, getToolConfig } from "#config";
 import type { K8sConfig } from "#config";
+import { collectProcessOutput } from "#shared/exec";
+import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
+import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
 import { isKubectlCommandAllowed } from "./security";
 
 export class K8sService extends Context.Service<
@@ -102,6 +105,24 @@ export class K8sService extends Context.Service<
             ),
           );
 
+        const runPrerequisiteCommand = (command: ChildProcess.Command, label: string) =>
+          Effect.scoped(
+            Effect.gen(function* () {
+              const process = yield* executor.spawn(command);
+              return yield* collectProcessOutput(process);
+            }),
+          ).pipe(
+            Effect.mapError(
+              (platformError) =>
+                new K8sCommandError({
+                  message: `Prerequisite command failed (${label}): ${String(platformError)}`,
+                  command: label,
+                  exitCode: -1,
+                  stderr: String(platformError),
+                }),
+            ),
+          );
+
         const resolveContext = Effect.fn("K8sService.resolveContext")(function* (
           profile: string | undefined,
           k8sConfig: K8sConfig,
@@ -172,27 +193,44 @@ export class K8sService extends Context.Service<
         ) {
           const k8sConfig = yield* requireK8sConfig(profile);
           const timeoutMs = k8sConfig.timeoutMs ?? 60000;
-          const context = yield* resolveContext(profile, k8sConfig);
-          const fullCommand = `kubectl --context ${context} ${cmd}`;
-
-          const resultOption = yield* runShellCommand(fullCommand, timeoutMs);
-
-          if (Option.isNone(resultOption)) {
-            return yield* new K8sTimeoutError({
-              message: `Command timed out after ${timeoutMs}ms`,
-              command: fullCommand,
-              timeoutMs,
-            });
-          }
-
-          const result = resultOption.value;
-
-          return {
-            stdout: result.stdout,
-            stderr: result.stderr,
-            exitCode: result.exitCode,
-            command: fullCommand,
-          };
+          return yield* runWithProfilePrerequisites(
+            config ?? {},
+            k8sConfig,
+            runPrerequisiteCommand,
+            Effect.gen(function* () {
+              const context = yield* resolveContext(profile, k8sConfig);
+              const fullCommand = `kubectl --context ${context} ${cmd}`;
+
+              const resultOption = yield* runShellCommand(fullCommand, timeoutMs);
+
+              if (Option.isNone(resultOption)) {
+                return yield* new K8sTimeoutError({
+                  message: `Command timed out after ${timeoutMs}ms`,
+                  command: fullCommand,
+                  timeoutMs,
+                });
+              }
+
+              const result = resultOption.value;
+
+              return {
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode,
+                command: fullCommand,
+              };
+            }),
+          ).pipe(
+            Effect.mapError((error) =>
+              isPrerequisiteRunError(error)
+                ? new K8sContextError({
+                    message: error.message,
+                    clusterId: k8sConfig.clusterId,
+                    hint: error.hint,
+                  })
+                : error,
+            ),
+          );
         });
 
         const runCommand = Effect.fn("K8sService.runCommand")(function* (

package/src/shared/exec.ts

@@ -10,6 +10,18 @@ export class ExecError extends Schema.TaggedErrorClass<ExecError>()("ExecError",
   stderr: Schema.String,
 }) {}
 
+export const collectProcessOutput = (process: ChildProcessSpawner.ChildProcessHandle) =>
+  Effect.gen(function* () {
+    const stdoutChunk = yield* process.stdout.pipe(Stream.decodeText(), Stream.runCollect);
+    const stderrChunk = yield* process.stderr.pipe(Stream.decodeText(), Stream.runCollect);
+
+    const stdout = stdoutChunk.join("");
+    const stderr = stderrChunk.join("");
+    const exitCode = yield* process.exitCode;
+
+    return { stdout, stderr, exitCode };
+  });
+
 export const execEffect = (
   commandStr: string,
   timeoutMs: number = DEFAULT_TIMEOUT_MS,
@@ -29,12 +41,7 @@ export const execEffect = (
 
       const process = yield* executor.spawn(command);
 
-      const stdoutChunk = yield* process.stdout.pipe(Stream.decodeText(), Stream.runCollect);
-      const stderrChunk = yield* process.stderr.pipe(Stream.decodeText(), Stream.runCollect);
-
-      const stdout = stdoutChunk.join("");
-      const stderr = stderrChunk.join("");
-      const exitCode = yield* process.exitCode;
+      const { stdout, stderr, exitCode } = yield* collectProcessOutput(process);
 
       if (exitCode !== 0) {
         return yield* new ExecError({

package/src/shared/prerequisites/errors.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+
+export class PrerequisiteRunError extends Schema.TaggedErrorClass<PrerequisiteRunError>()(
+  "PrerequisiteRunError",
+  {
+    message: Schema.String,
+    hint: Schema.optionalKey(Schema.String),
+  },
+) {}
+
+export const isPrerequisiteRunError = (error: unknown): error is PrerequisiteRunError =>
+  error instanceof PrerequisiteRunError;

package/src/shared/prerequisites/runtime.ts

@@ -0,0 +1,200 @@
+import { Clock, Duration, Effect, Result } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+
+import type { AgentToolsConfig, ProfilePrerequisites } from "#config/types";
+import type { PrerequisiteCommandRunner, ResolvedVpnDriver } from "#shared/prerequisites/types";
+
+import { normalizeProfilePrerequisites } from "#shared/prerequisites/config";
+import { PrerequisiteRunError } from "#shared/prerequisites/errors";
+import { missingVpnToolHint, resolveVpnDriverConfig } from "#shared/prerequisites/vpn";
+
+const makeVpnCommand = (driver: ResolvedVpnDriver, action: "status" | "start" | "stop") => {
+  if (driver.type === "macos-scutil") {
+    const args =
+      action === "status"
+        ? ["--nc", "status", driver.serviceName]
+        : action === "start"
+          ? ["--nc", "start", driver.serviceName]
+          : ["--nc", "stop", driver.serviceName];
+
+    return {
+      command: ChildProcess.make("scutil", args, { stdout: "pipe", stderr: "pipe" }),
+      label: ["scutil", ...args].join(" "),
+    };
+  }
+
+  if (driver.type === "linux-nmcli") {
+    const args =
+      action === "status"
+        ? ["-t", "-f", "NAME", "connection", "show", "--active"]
+        : action === "start"
+          ? ["connection", "up", driver.connectionName]
+          : ["connection", "down", driver.connectionName];
+
+    return {
+      command: ChildProcess.make("nmcli", args, { stdout: "pipe", stderr: "pipe" }),
+      label: ["nmcli", ...args].join(" "),
+    };
+  }
+
+  const args =
+    action === "stop"
+      ? [driver.entryName, "/disconnect"]
+      : action === "start"
+        ? [driver.entryName]
+        : [];
+  return {
+    command: ChildProcess.make("rasdial", args, { stdout: "pipe", stderr: "pipe" }),
+    label: ["rasdial", ...args].join(" "),
+  };
+};
+
+const isVpnConnectedOutput = (driver: ResolvedVpnDriver, stdout: string) => {
+  if (driver.type === "macos-scutil") {
+    return stdout.includes("Connected");
+  }
+
+  if (driver.type === "linux-nmcli") {
+    return stdout
+      .trim()
+      .split("\n")
+      .some((line) => line.trim() === driver.connectionName);
+  }
+
+  return stdout.includes(driver.entryName);
+};
+
+const isVpnConnected = <E>(driver: ResolvedVpnDriver, runCommand: PrerequisiteCommandRunner<E>) => {
+  const statusCommand = makeVpnCommand(driver, "status");
+  return runCommand(statusCommand.command, statusCommand.label).pipe(
+    Effect.result,
+    Effect.map((result) => {
+      if (Result.isFailure(result)) {
+        return false;
+      }
+
+      return result.success.exitCode === 0 && isVpnConnectedOutput(driver, result.success.stdout);
+    }),
+  );
+};
+
+const waitForVpn = <E>(
+  driver: ResolvedVpnDriver,
+  timeoutMs: number,
+  runCommand: PrerequisiteCommandRunner<E>,
+) =>
+  Effect.gen(function* () {
+    const startTime = yield* Clock.currentTimeMillis;
+    const deadline = Number(startTime) + timeoutMs;
+    let result: boolean | undefined;
+
+    yield* Effect.whileLoop({
+      while: () => result === undefined,
+      body: () =>
+        Effect.gen(function* () {
+          if (yield* isVpnConnected(driver, runCommand)) {
+            result = true;
+            return;
+          }
+
+          const now = yield* Clock.currentTimeMillis;
+          if (Number(now) >= deadline) {
+            result = false;
+            return;
+          }
+
+          yield* Effect.sleep(Duration.millis(500));
+        }),
+      step: () => undefined,
+    });
+
+    return result === true;
+  });
+
+export const runWithProfilePrerequisites = <A, E, CommandError>(
+  config: AgentToolsConfig,
+  profile: ProfilePrerequisites,
+  runCommand: PrerequisiteCommandRunner<CommandError>,
+  effect: Effect.Effect<A, E, never>,
+): Effect.Effect<A, E | PrerequisiteRunError, never> => {
+  const prerequisites = normalizeProfilePrerequisites(profile);
+  const vpnPrerequisites = prerequisites.filter((prerequisite) => prerequisite.type === "vpn");
+
+  if (vpnPrerequisites.length === 0) {
+    return effect;
+  }
+
+  return Effect.gen(function* () {
+    const startedDrivers: Array<{ driver: ResolvedVpnDriver; cooldownMs: number }> = [];
+
+    for (const prerequisite of vpnPrerequisites) {
+      const vpnConfig = config.vpns?.[prerequisite.key];
+      if (!vpnConfig) {
+        return yield* new PrerequisiteRunError({
+          message: `VPN prerequisite "${prerequisite.key}" is not defined.`,
+          hint: `Add vpns.${prerequisite.key} to agent-tools.json5 or remove the prerequisite.`,
+        });
+      }
+
+      const driverResolution = resolveVpnDriverConfig(vpnConfig);
+      if (!driverResolution.success) {
+        return yield* new PrerequisiteRunError({
+          message: driverResolution.error,
+          hint: driverResolution.hint,
+        });
+      }
+
+      const driver = driverResolution.driver;
+      const wasConnected = yield* isVpnConnected(driver, runCommand);
+      if (wasConnected) {
+        continue;
+      }
+
+      const startCommand = makeVpnCommand(driver, "start");
+      const startResult = yield* runCommand(startCommand.command, startCommand.label).pipe(
+        Effect.mapError(
+          () =>
+            new PrerequisiteRunError({
+              message: `Failed to start VPN prerequisite "${prerequisite.key}".`,
+              hint: missingVpnToolHint(driver),
+            }),
+        ),
+      );
+
+      if (startResult.exitCode !== 0) {
+        const stderr = startResult.stderr.trim();
+        return yield* new PrerequisiteRunError({
+          message:
+            stderr !== "" ? stderr : `Failed to start VPN prerequisite "${prerequisite.key}".`,
+          hint: missingVpnToolHint(driver),
+        });
+      }
+
+      const ready = yield* waitForVpn(driver, vpnConfig.connectTimeoutMs ?? 30000, runCommand);
+      if (!ready) {
+        return yield* new PrerequisiteRunError({
+          message: `VPN prerequisite "${prerequisite.key}" did not connect within timeout.`,
+          hint: missingVpnToolHint(driver),
+        });
+      }
+
+      const cleanup = prerequisite.cleanup ?? vpnConfig.defaultCleanup ?? "stop-if-started";
+      if (cleanup === "stop-if-started") {
+        startedDrivers.push({ driver, cooldownMs: vpnConfig.cooldownMs ?? 0 });
+      }
+    }
+
+    const cleanup = Effect.gen(function* () {
+      for (const started of startedDrivers.toReversed()) {
+        if (started.cooldownMs > 0) {
+          yield* Effect.sleep(Duration.millis(started.cooldownMs));
+        }
+
+        const stopCommand = makeVpnCommand(started.driver, "stop");
+        yield* runCommand(stopCommand.command, stopCommand.label).pipe(Effect.ignore);
+      }
+    });
+
+    return yield* effect.pipe(Effect.ensuring(cleanup));
+  });
+};

package/src/shared/prerequisites/types.ts

@@ -1,3 +1,6 @@
+import type { Effect } from "effect";
+import type { ChildProcess } from "effect/unstable/process";
+
 import type {
   LinuxNmcliVpnDriverConfig,
   MacosScutilVpnDriverConfig,
@@ -19,3 +22,14 @@ export type ResolvedVpnDriver =
 export type VpnDriverResolution =
   | { success: true; driver: ResolvedVpnDriver }
   | { success: false; error: string; hint: string };
+
+export type PrerequisiteCommandResult = {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+};
+
+export type PrerequisiteCommandRunner<E> = (
+  command: ChildProcess.Command,
+  label: string,
+) => Effect.Effect<PrerequisiteCommandResult, E, never>;