@blogic-cz/agent-tools 0.14.5 → 0.14.8

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.5",
+  "version": "0.14.8",
   "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/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(" "),
     };
   }
 
@@ -126,83 +133,116 @@ export const runWithProfilePrerequisites = <A, E, CommandError>(
   }
 
   return Effect.gen(function* () {
-    if (options?.tryWithoutPrerequisites) {
-      const directResult = yield* effect.pipe(Effect.result);
+    const shouldTryDirect = options?.tryWithoutPrerequisites === true;
+
+    const tryDirect = () => effect.pipe(Effect.result);
+
+    if (shouldTryDirect) {
+      const directResult = yield* tryDirect();
       if (Result.isSuccess(directResult)) {
         return directResult.success;
       }
     }
 
-    const startedDrivers: Array<{ driver: ResolvedVpnDriver; cooldownMs: number }> = [];
+    const prerequisiteResult = yield* 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.`,
-        });
-      }
+      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 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 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),
-        });
-      }
+        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 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 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 cleanup = prerequisite.cleanup ?? vpnConfig.defaultCleanup ?? "stop-if-started";
-      if (cleanup === "stop-if-started") {
-        startedDrivers.push({ driver, cooldownMs: vpnConfig.cooldownMs ?? 0 });
+        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 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);
         }
+      });
 
-        const stopCommand = makeVpnCommand(started.driver, "stop");
-        yield* runCommand(stopCommand.command, stopCommand.label).pipe(Effect.ignore);
+      return yield* effect.pipe(Effect.ensuring(cleanup));
+    }).pipe(Effect.result);
+
+    if (Result.isSuccess(prerequisiteResult)) {
+      return prerequisiteResult.success;
+    }
+
+    if (shouldTryDirect && prerequisiteResult.failure instanceof PrerequisiteRunError) {
+      const directRetryResult = yield* tryDirect();
+      if (Result.isSuccess(directRetryResult)) {
+        return directRetryResult.success;
       }
-    });
+      if (!(directRetryResult.failure instanceof PrerequisiteRunError)) {
+        return yield* Effect.fail(directRetryResult.failure);
+      }
+    }
 
-    return yield* effect.pipe(Effect.ensuring(cleanup));
+    return yield* Effect.fail(prerequisiteResult.failure);
   });
 };

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") {