@blogic-cz/agent-tools 0.14.37 → 0.14.39

package/package.json

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

@@ -95,6 +95,29 @@
         "repo": {
           "type": "string",
           "description": "Repository name."
+        },
+        "prTitle": {
+          "$ref": "#/definitions/GitHubPrTitlePolicy"
+        }
+      }
+    },
+    "GitHubPrTitlePolicy": {
+      "description": "Optional pull request title validation policy for this repository profile.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pattern", "expected"],
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "JavaScript regular expression source that valid PR titles must match."
+        },
+        "expected": {
+          "type": "string",
+          "description": "Human-readable required title format shown when validation fails."
+        },
+        "example": {
+          "type": "string",
+          "description": "Example valid title shown when validation fails."
         }
       }
     },

package/src/config/index.ts

@@ -11,6 +11,7 @@ export type {
   AuditConfig,
   CliToolOverride,
   CredentialGuardConfig,
+  GitHubPrTitlePolicy,
   GitHubRepoConfig,
 } from "./types";
 

package/src/config/loader.ts

@@ -80,6 +80,7 @@ const K8sConfigSchema = Schema.Struct({
   clusterId: Schema.String,
   namespaces: Schema.Record(Schema.String, Schema.String),
   timeoutMs: Schema.optionalKey(Schema.Number),
+  apiProbeTimeoutMs: Schema.optionalKey(Schema.Number),
   prerequisites: Schema.optionalKey(PrerequisitesSchema),
   vpn: Schema.optionalKey(Schema.String),
 });
@@ -141,6 +142,13 @@ const AuditConfigSchema = Schema.Struct({
 const GitHubRepoConfigSchema = Schema.Struct({
   owner: Schema.String,
   repo: Schema.String,
+  prTitle: Schema.optionalKey(
+    Schema.Struct({
+      pattern: Schema.String,
+      expected: Schema.String,
+      example: Schema.optionalKey(Schema.String),
+    }),
+  ),
 });
 
 const KNOWN_TOP_LEVEL_KEYS = new Set([

package/src/config/types.ts

@@ -71,6 +71,13 @@ export type K8sConfig = ProfilePrerequisites & {
   /** Named namespaces, e.g. { test: "my-app-test", prod: "my-app-prod" } */
   namespaces: Record<string, string>;
   timeoutMs?: number;
+  /**
+   * Timeout in milliseconds for the cheap Kubernetes API-server reachability probe run
+   * before each command. When the cluster API is unreachable (VPN down / off the office
+   * network, or the API degraded) a real kubectl command hangs until `timeoutMs`; the
+   * probe lets it fail fast with a clear message instead. Set to 0 to disable. Defaults to 2000.
+   */
+  apiProbeTimeoutMs?: number;
 };
 
 /** Single database environment connection details */
@@ -154,9 +161,16 @@ export type AuditConfig = {
 };
 
 /** Single GitHub repository configuration */
+export type GitHubPrTitlePolicy = {
+  pattern: string;
+  expected: string;
+  example?: string;
+};
+
 export type GitHubRepoConfig = {
   owner: string;
   repo: string;
+  prTitle?: GitHubPrTitlePolicy;
 };
 
 /**

package/src/db-tool/service.ts

@@ -8,6 +8,7 @@ import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
 import { resolveEnvTemplate } from "#shared/env-template";
 import { resolveEnvironmentScopedPrerequisites } from "#shared/prerequisites/config";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
+import { buildApiProbeArgs } from "#shared/k8s-probe";
 import { DbConfigService, DbConfigServiceLayer, TUNNEL_CHECK_INTERVAL_MS } from "./config-service";
 import {
   DbConnectionError,
@@ -51,26 +52,8 @@ export function resolveDbAccessMode(
   };
 }
 
-/**
- * Build the kubectl args for the lightweight API-server reachability probe.
- * Hitting `/version` via `--raw` is the cheapest authenticated round-trip; `--request-timeout`
- * bounds it so an unreachable server (VPN down, off the office network) fails fast instead of
- * letting a subsequent `kubectl port-forward` hang on a silent TCP connect.
- */
-export function buildApiProbeArgs(
-  kubeconfig: string | undefined,
-  context: string,
-  timeoutMs: number,
-): string[] {
-  return [
-    ...(kubeconfig ? ["--kubeconfig", kubeconfig] : []),
-    "--context",
-    context,
-    "get",
-    "--raw=/version",
-    `--request-timeout=${timeoutMs}ms`,
-  ];
-}
+// Re-exported from the shared probe so existing `#db/service` consumers keep working.
+export { buildApiProbeArgs } from "#shared/k8s-probe";
 
 export class DbService extends Context.Service<
   DbService,

package/src/gh-tool/pr/core.ts

@@ -21,6 +21,45 @@ import { runLocalCommand } from "./helpers";
 const CHECK_JSON_FIELDS = "name,state,bucket,link";
 const GITHUB_ACTIONS_RUN_ID_RE = /github\.com\/[^/]+\/[^/]+\/actions\/runs\/(\d+)/;
 
+const validatePRTitle = Effect.fn("pr.validatePRTitle")(function* (title: string) {
+  const gh = yield* GitHubService;
+  const repoConfig = yield* gh.getRepoConfig();
+  const policy = repoConfig?.prTitle;
+
+  if (!policy) {
+    return;
+  }
+
+  const pattern = yield* Effect.try({
+    try: () => new RegExp(policy.pattern),
+    catch: (error) =>
+      new GitHubCommandError({
+        command: "pr title validation",
+        exitCode: 1,
+        stderr: `Invalid PR title policy regex: ${error instanceof Error ? error.message : String(error)}`,
+        message: "Invalid PR title policy regex",
+      }),
+  });
+
+  if (pattern.test(title)) {
+    return;
+  }
+
+  const lines = [
+    "PR title does not match the required format.",
+    `Got: ${title}`,
+    `Expected: ${policy.expected}`,
+    ...(policy.example ? [`Example: ${policy.example}`] : []),
+  ];
+
+  return yield* new GitHubCommandError({
+    command: "pr title validation",
+    exitCode: 1,
+    stderr: lines.join("\n"),
+    message: lines[0] ?? "PR title does not match the required format.",
+  });
+});
+
 type WorkflowRunJobsForRerun = {
   databaseId: number;
   jobs: Array<{
@@ -422,6 +461,7 @@ export const createPR = Effect.fn("pr.createPR")(function* (opts: {
   head: string | null;
 }) {
   const gh = yield* GitHubService;
+  yield* validatePRTitle(opts.title);
 
   // When --head is provided (e.g. GitButler workspace), use `gh pr list --head`
   // to find existing PR since `gh pr view` relies on the current git branch.
@@ -719,6 +759,10 @@ export const editPR = Effect.fn("pr.editPR")(function* (opts: {
   }
 
   const gh = yield* GitHubService;
+  if (opts.title !== null) {
+    yield* validatePRTitle(opts.title);
+  }
+
   const repo = yield* gh.getRepoInfo();
 
   const editArgs = [

package/src/gh-tool/service.ts

@@ -1,11 +1,12 @@
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { Context, Effect, Layer, Stream } from "effect";
 
+import type { GitHubRepoConfig } from "#config";
 import type { RepoInfo } from "./types";
 
 import { GH_BINARY } from "./config";
 import { GitHubAuthError, GitHubCommandError, GitHubNotFoundError } from "./errors";
-import { ConfigService, resolveGitHubRepoTarget } from "#config";
+import { ConfigService, getGitHubConfig, resolveGitHubRepoTarget } from "#config";
 
 type GhResult = {
   stdout: string;
@@ -24,6 +25,7 @@ export class GitHubService extends Context.Service<
       query: string,
       variables: Record<string, string | number | null>,
     ) => Effect.Effect<unknown, GhError>;
+    readonly getRepoConfig: () => Effect.Effect<GitHubRepoConfig | undefined, never>;
     readonly getRepoInfo: () => Effect.Effect<RepoInfo, GhError>;
     readonly withRepoTarget: <A, E, R>(
       target: string | null,
@@ -76,6 +78,22 @@ export class GitHubService extends Context.Service<
             return yield* effect.pipe(Effect.provideService(RepoTarget, resolved));
           });
 
+        const getRepoConfig = Effect.fn("GitHubService.getRepoConfig")(function* () {
+          const ghRepo = yield* RepoTarget;
+          const repos = config?.github;
+
+          if (repos && ghRepo) {
+            const repoConfig = Object.values(repos).find(
+              (repo) => `${repo.owner}/${repo.repo}` === ghRepo,
+            );
+            if (repoConfig) {
+              return repoConfig;
+            }
+          }
+
+          return getGitHubConfig(config);
+        });
+
         const executeGh = (args: string[]) =>
           Effect.scoped(
             Effect.gen(function* () {
@@ -242,7 +260,7 @@ export class GitHubService extends Context.Service<
           return repoInfo;
         });
 
-        return { runGh, runGhJson, runGraphQL, getRepoInfo, withRepoTarget };
+        return { runGh, runGhJson, runGraphQL, getRepoConfig, getRepoInfo, withRepoTarget };
       }),
     ),
   );

package/src/k8s-tool/service.ts

@@ -15,6 +15,7 @@ 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 { buildApiProbeArgs } from "#shared/k8s-probe";
 import { isKubectlCommandAllowed } from "./security";
 
 export class K8sService extends Context.Service<
@@ -146,6 +147,40 @@ export class K8sService extends Context.Service<
             ),
           );
 
+        /**
+         * Cheap pre-flight: is the cluster API reachable right now? Returns true when the probe
+         * is disabled (apiProbeTimeoutMs <= 0) so behaviour is unchanged unless a probe can run.
+         * A false result lets the command fail fast instead of hanging until the full timeoutMs.
+         */
+        const probeApiReachable = (
+          context: string,
+          kubeconfig: string | undefined,
+          timeoutMs: number,
+        ) =>
+          Effect.gen(function* () {
+            if (timeoutMs <= 0) {
+              return true;
+            }
+
+            const probe = ChildProcess.make(
+              "kubectl",
+              buildApiProbeArgs(kubeconfig, context, timeoutMs),
+              {
+                stdout: "pipe",
+                stderr: "pipe",
+              },
+            );
+
+            const result = yield* Effect.scoped(
+              Effect.gen(function* () {
+                const process = yield* executor.spawn(probe);
+                return yield* collectProcessOutput(process);
+              }),
+            ).pipe(Effect.catch(() => Effect.succeed({ stdout: "", stderr: "", exitCode: 1 })));
+
+            return result.exitCode === 0;
+          });
+
         const resolveContext = Effect.fn("K8sService.resolveContext")(function* (
           profile: string | undefined,
           k8sConfig: K8sConfig,
@@ -223,12 +258,23 @@ export class K8sService extends Context.Service<
         ) {
           const k8sConfig = yield* requireK8sConfig(profile);
           const timeoutMs = k8sConfig.timeoutMs ?? 60000;
+          const apiProbeTimeoutMs = k8sConfig.apiProbeTimeoutMs ?? 2000;
           return yield* runWithProfilePrerequisites(
             config ?? {},
             k8sConfig,
             runPrerequisiteCommand,
             Effect.gen(function* () {
               const { context, kubeconfig } = yield* resolveContext(profile, k8sConfig);
+
+              const reachable = yield* probeApiReachable(context, kubeconfig, apiProbeTimeoutMs);
+              if (!reachable) {
+                return yield* new K8sContextError({
+                  message: `Kubernetes API server (${k8sConfig.clusterId}) not reachable within ${apiProbeTimeoutMs}ms. VPN likely not connected, or the cluster API is degraded.`,
+                  clusterId: k8sConfig.clusterId,
+                  hint: "Check the VPN connection and cluster health, then retry. Set kubernetes.apiProbeTimeoutMs to 0 in agent-tools.json5 to disable this pre-flight probe.",
+                });
+              }
+
               const fullCommand = withKubeconfig(`kubectl --context ${context} ${cmd}`, kubeconfig);
 
               const resultOption = yield* runShellCommand(fullCommand, timeoutMs);

package/src/shared/k8s-probe.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared kubectl API-server reachability probe, used by every VPN-gated tool
+ * (db-tool, k8s-tool) to fail fast instead of hanging on a silently unreachable cluster.
+ *
+ * Hitting `/version` via `--raw` is the cheapest authenticated round-trip; `--request-timeout`
+ * bounds it so an unreachable server (VPN down / off the office network, or the cluster API
+ * degraded) fails in ~`timeoutMs` with a clear message instead of waiting out the tool's full
+ * command/tunnel timeout.
+ */
+export function buildApiProbeArgs(
+  kubeconfig: string | undefined,
+  context: string,
+  timeoutMs: number,
+): string[] {
+  return [
+    ...(kubeconfig ? ["--kubeconfig", kubeconfig] : []),
+    "--context",
+    context,
+    "get",
+    "--raw=/version",
+    `--request-timeout=${timeoutMs}ms`,
+  ];
+}