@blogic-cz/agent-tools 0.18.0 → 1.0.0

package/src/azdo-tool/service.ts

@@ -0,0 +1,322 @@
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { Context, Effect, Layer, Option, Stream } from "effect";
+
+import type { InvokeParams } from "./types";
+import type { AzureConfig } from "#config/types";
+
+import { DIRECT_AZ_COMMANDS, STANDALONE_AZ_COMMANDS } from "./config";
+import { AzdoSecurityError, AzdoCommandError, AzdoTimeoutError, AzdoParseError } from "./errors";
+import { isCommandAllowed, isInvokeAllowed } from "./security";
+import { transformCmdOutput } from "./transformers";
+import { ConfigService, getToolConfig } from "#config";
+import { renderCommandLine, tokenizeCommandLine } from "#shared/exec";
+
+export class AzdoService extends Context.Service<
+  AzdoService,
+  {
+    readonly runCommand: (
+      cmd: string,
+      project?: string,
+    ) => Effect.Effect<
+      string,
+      AzdoSecurityError | AzdoCommandError | AzdoTimeoutError | AzdoParseError
+    >;
+    readonly runInvoke: (
+      params: InvokeParams,
+    ) => Effect.Effect<
+      unknown,
+      AzdoSecurityError | AzdoCommandError | AzdoTimeoutError | AzdoParseError
+    >;
+  }
+>()("@agent-tools/AzdoService") {
+  static readonly layer = Layer.effect(
+    AzdoService,
+    Effect.gen(function* () {
+      const config = yield* ConfigService;
+      const azConfig = getToolConfig<AzureConfig>(config, "azure");
+
+      if (!azConfig) {
+        const noConfigError = new AzdoCommandError({
+          message: "No Azure configuration found. Add an 'azure' section to agent-tools.json5.",
+          command: "unknown",
+          exitCode: -1,
+          hint: "Create or update agent-tools.json5 with an 'azure' section containing organization and defaultProject",
+        });
+        return {
+          runCommand: (_cmd: string, _project?: string) => Effect.fail(noConfigError),
+          runInvoke: (_params: InvokeParams) => Effect.fail(noConfigError),
+        };
+      }
+
+      const executor = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+      const runAzCommand = (argv: readonly string[], timeoutMs: number) =>
+        Effect.scoped(
+          Effect.gen(function* () {
+            const command = ChildProcess.make("az", argv, {
+              stdout: "pipe",
+              stderr: "pipe",
+            });
+            const process = yield* executor.spawn(command);
+
+            const stdoutChunk = yield* process.stdout.pipe(Stream.decodeText(), Stream.runCollect);
+            const stdout = stdoutChunk.join("");
+
+            const stderrChunk = yield* process.stderr.pipe(Stream.decodeText(), Stream.runCollect);
+            const stderr = stderrChunk.join("");
+
+            const exitCode = yield* process.exitCode;
+
+            return { stdout, stderr, exitCode };
+          }),
+        ).pipe(
+          Effect.timeoutOption(timeoutMs),
+          Effect.mapError(
+            (platformError) =>
+              new AzdoCommandError({
+                message: `Command execution failed: ${platformError.message}`,
+                command: renderCommandLine(["az", ...argv]),
+                exitCode: -1,
+                hint: "Check that the az CLI is installed and authenticated",
+                nextCommand: "az login",
+                retryable: true,
+              }),
+          ),
+        );
+
+      const resolveProject = (project?: string) => project ?? azConfig.defaultProject;
+
+      const runCommand = Effect.fn("AzdoService.runCommand")(function* (
+        cmd: string,
+        project?: string,
+      ) {
+        const projectName = resolveProject(project);
+
+        const securityCheck = isCommandAllowed(cmd);
+        if (!securityCheck.allowed) {
+          return yield* new AzdoSecurityError({
+            message: securityCheck.reason ?? "Command not allowed",
+            command: cmd,
+            hint: "Only read-only az devops commands are allowed. Use build helpers for common operations.",
+          });
+        }
+
+        const invokeParams = parseInvokeFromCommand(cmd);
+        if (invokeParams) {
+          const invokeResult = yield* runInvoke({
+            ...invokeParams,
+            project: projectName,
+          });
+          return JSON.stringify(invokeResult);
+        }
+
+        const cmdWords = cmd.trim().split(/\s+/);
+        const firstWord = cmdWords[0]?.toLowerCase() ?? "";
+        const isDirectCommand = DIRECT_AZ_COMMANDS.includes(
+          firstWord as (typeof DIRECT_AZ_COMMANDS)[number],
+        );
+        const isStandaloneCommand = STANDALONE_AZ_COMMANDS.includes(
+          firstWord as (typeof STANDALONE_AZ_COMMANDS)[number],
+        );
+
+        const cmdArgv = tokenizeCommandLine(cmd);
+        const scopeArgv = [
+          "--organization",
+          azConfig.organization,
+          "--project",
+          projectName,
+        ] as const;
+
+        const argv = isStandaloneCommand
+          ? cmdArgv
+          : isDirectCommand
+            ? [...cmdArgv, ...scopeArgv]
+            : ["devops", ...cmdArgv, ...scopeArgv];
+
+        const fullCommand = renderCommandLine(["az", ...argv]);
+        const resultOption = yield* runAzCommand(argv, azConfig.timeoutMs ?? 60000);
+
+        if (Option.isNone(resultOption)) {
+          return yield* new AzdoTimeoutError({
+            message: `Command timed out after ${azConfig.timeoutMs ?? 60000}ms`,
+            command: fullCommand,
+            timeoutMs: azConfig.timeoutMs ?? 60000,
+            retryable: true,
+            hint: "The command took too long. Retry or increase timeoutMs in azure config.",
+          });
+        }
+
+        const result = resultOption.value;
+
+        if (result.exitCode !== 0) {
+          return yield* new AzdoCommandError({
+            message: result.stderr || `Command failed with exit code ${result.exitCode}`,
+            command: fullCommand,
+            exitCode: result.exitCode,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+          });
+        }
+
+        const output = result.stdout.trim();
+        const transformed = transformCmdOutput(output);
+
+        if (typeof transformed === "string") {
+          return transformed;
+        }
+
+        return JSON.stringify(transformed);
+      });
+
+      const runInvoke = Effect.fn("AzdoService.runInvoke")(function* (params: InvokeParams) {
+        const securityCheck = isInvokeAllowed(params);
+        if (!securityCheck.allowed) {
+          return yield* new AzdoSecurityError({
+            message: securityCheck.reason ?? "Invoke not allowed",
+            command: `invoke --area ${params.area} --resource ${params.resource}`,
+            hint: "Only allowed invoke areas/resources can be used. Check azdo-tool security config.",
+          });
+        }
+
+        const argv = ["devops", "invoke", "--area", params.area, "--resource", params.resource];
+
+        const projectName = resolveProject(params.project);
+
+        const routeParameters = {
+          project: projectName,
+          ...params.routeParameters,
+        };
+
+        if (Object.keys(routeParameters).length > 0) {
+          argv.push(
+            "--route-parameters",
+            ...Object.entries(routeParameters).map(([k, v]) => `${k}=${v}`),
+          );
+        }
+
+        if (params.queryParameters) {
+          argv.push(
+            "--query-parameters",
+            ...Object.entries(params.queryParameters).map(([k, v]) => `${k}=${v}`),
+          );
+        }
+
+        argv.push("--organization", azConfig.organization, "--output", "json");
+
+        const fullCommand = renderCommandLine(["az", ...argv]);
+        const resultOption = yield* runAzCommand(argv, azConfig.timeoutMs ?? 60000);
+
+        if (Option.isNone(resultOption)) {
+          return yield* new AzdoTimeoutError({
+            message: `Invoke timed out after ${azConfig.timeoutMs ?? 60000}ms`,
+            command: fullCommand,
+            timeoutMs: azConfig.timeoutMs ?? 60000,
+            retryable: true,
+            hint: "The invoke took too long. Retry or increase timeoutMs in azure config.",
+          });
+        }
+
+        const result = resultOption.value;
+
+        if (result.exitCode !== 0) {
+          return yield* new AzdoCommandError({
+            message: result.stderr || `Invoke failed with exit code ${result.exitCode}`,
+            command: fullCommand,
+            exitCode: result.exitCode,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+          });
+        }
+
+        const jsonData = yield* Effect.try({
+          try: () => JSON.parse(result.stdout) as unknown,
+          catch: () =>
+            new AzdoParseError({
+              message: `Failed to parse JSON response from invoke`,
+              rawOutput: result.stdout.slice(0, 500),
+              hint: "The az CLI returned non-JSON output. Ensure --output json is used.",
+            }),
+        });
+        return jsonData;
+      });
+
+      return { runCommand, runInvoke };
+    }),
+  );
+}
+
+export const AzdoServiceLayer = AzdoService.layer;
+
+function parseInvokeFromCommand(cmd: string): InvokeParams | undefined {
+  const words = cmd.trim().split(/\s+/);
+  const loweredWords = words.map((word) => word.toLowerCase());
+
+  if (!loweredWords.includes("invoke")) {
+    return undefined;
+  }
+
+  const area = extractOptionValue(words, "--area");
+  const resource = extractOptionValue(words, "--resource");
+
+  if (!area || !resource) {
+    return undefined;
+  }
+
+  const routeParameters = extractParametersOption(words, "--route-parameters");
+  const queryParameters = extractParametersOption(words, "--query-parameters");
+  const apiVersion = extractOptionValue(words, "--api-version");
+
+  const mergedQueryParameters = apiVersion
+    ? {
+        ...queryParameters,
+        "api-version": apiVersion,
+      }
+    : queryParameters;
+
+  return {
+    area,
+    resource,
+    ...(routeParameters ? { routeParameters } : {}),
+    ...(mergedQueryParameters ? { queryParameters: mergedQueryParameters } : {}),
+  };
+}
+
+function extractOptionValue(args: readonly string[], optionName: string): string | undefined {
+  const optionIndex = args.findIndex((arg) => arg.toLowerCase() === optionName.toLowerCase());
+
+  if (optionIndex === -1) {
+    return undefined;
+  }
+
+  return args[optionIndex + 1];
+}
+
+function extractParametersOption(
+  args: readonly string[],
+  optionName: string,
+): Record<string, string | number> | undefined {
+  const optionIndex = args.findIndex((arg) => arg.toLowerCase() === optionName.toLowerCase());
+
+  if (optionIndex === -1) {
+    return undefined;
+  }
+
+  const result: Record<string, string | number> = {};
+
+  for (let i = optionIndex + 1; i < args.length; i++) {
+    const token = args[i];
+    if (!token || token.startsWith("--")) {
+      break;
+    }
+
+    const equalsIndex = token.indexOf("=");
+    if (equalsIndex === -1) {
+      continue;
+    }
+
+    const key = token.slice(0, equalsIndex);
+    const rawValue = token.slice(equalsIndex + 1);
+    const parsedNumber = Number(rawValue);
+    result[key] = Number.isNaN(parsedNumber) ? rawValue : parsedNumber;
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}

package/src/azdo-tool/types.ts

@@ -0,0 +1,67 @@
+export type SecurityCheckResult = {
+  allowed: boolean;
+  command?: string;
+  reason?: string;
+};
+
+export type InvokeParams = {
+  area: string;
+  resource: string;
+  project?: string;
+  routeParameters?: Record<string, string | number>;
+  queryParameters?: Record<string, string | number>;
+};
+
+export type BuildJob = {
+  id: string;
+  parentId?: string | null;
+  type: "Job" | "Stage" | "Task" | "Phase" | "Checkpoint";
+  name: string;
+  state: "pending" | "inProgress" | "completed";
+  result?: "succeeded" | "failed" | "canceled" | "skipped" | null;
+  startTime?: string | null;
+  finishTime?: string | null;
+  errorCount?: number | null;
+  warningCount?: number | null;
+  log?: { id: number; url: string } | null;
+};
+
+export type BuildTimeline = {
+  records: BuildJob[];
+  id: string;
+  changeId: number;
+  lastChangedBy: string;
+  lastChangedOn: string;
+  url: string;
+};
+
+export type BuildLog = {
+  id: number;
+  type: string;
+  url: string;
+  lineCount?: number;
+};
+
+export type BuildLogs = {
+  count: number;
+  value: BuildLog[];
+};
+
+export type JobSummary = {
+  name: string;
+  state: string;
+  result?: string;
+  stage?: string;
+  duration?: string;
+  logId?: number;
+};
+
+export type PipelineRun = {
+  id: number;
+  buildNumber: string;
+  status: string;
+  result?: string;
+  sourceBranch: string;
+  startTime?: string;
+  finishTime?: string;
+};

package/src/config/index.ts

@@ -1,6 +1,7 @@
 export type {
   AgentToolsConfig,
   AzureConfig,
+  AzurePlatformConfig,
   K8sConfig,
   DbEnvConfig,
   DbAllowedMutationTargets,

package/src/config/loader.ts

@@ -88,6 +88,13 @@ const AzureConfigSchema = Schema.Struct({
   timeoutMs: Schema.optionalKey(Schema.Number),
 });
 
+const AzurePlatformConfigSchema = Schema.Struct({
+  subscription: Schema.String,
+  timeoutMs: Schema.optionalKey(Schema.Number),
+  production: Schema.optionalKey(Schema.Boolean),
+  allowedResourceGroups: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
 const K8sConfigSchema = Schema.Struct({
   kubeconfig: Schema.optionalKey(Schema.String),
   clusterId: Schema.String,
@@ -178,6 +185,7 @@ const GitHubRepoConfigSchema = Schema.Struct({
 const KNOWN_TOP_LEVEL_KEYS = new Set([
   "$schema",
   "azure",
+  "azurePlatform",
   "vpns",
   "kubernetes",
   "database",
@@ -193,6 +201,7 @@ const KNOWN_TOP_LEVEL_KEYS = new Set([
 const AgentToolsConfigSchema = Schema.Struct({
   $schema: Schema.optionalKey(Schema.String),
   azure: Schema.optionalKey(Schema.Record(Schema.String, AzureConfigSchema)),
+  azurePlatform: Schema.optionalKey(Schema.Record(Schema.String, AzurePlatformConfigSchema)),
   vpns: Schema.optionalKey(Schema.Record(Schema.String, VpnConfigSchema)),
   kubernetes: Schema.optionalKey(Schema.Record(Schema.String, K8sConfigSchema)),
   database: Schema.optionalKey(Schema.Record(Schema.String, DatabaseConfigSchema)),
@@ -378,7 +387,7 @@ export const ConfigServiceLayer = Layer.effect(
 
 type ProfiledSection = keyof Pick<
   AgentToolsConfig,
-  "azure" | "kubernetes" | "database" | "observability" | "logs"
+  "azure" | "azurePlatform" | "kubernetes" | "database" | "observability" | "logs"
 >;
 
 export function getToolConfig<T>(

package/src/config/types.ts

@@ -1,12 +1,28 @@
 import { Schema } from "effect";
 
-/** Azure DevOps profile configuration */
+/** Azure DevOps profile, consumed by azdo-tool. */
 export type AzureConfig = {
   organization: string;
   defaultProject: string;
   timeoutMs?: number;
 };
 
+/** Azure platform (PaaS) profile, consumed by az-tool. */
+export type AzurePlatformConfig = {
+  subscription: string;
+  timeoutMs?: number;
+  /**
+   * Require --profile to be passed explicitly before this subscription is
+   * touched. Defaults to true for profiles keyed "prod" or "production".
+   */
+  production?: boolean;
+  /**
+   * Resource groups this profile may address. Empty or absent means every
+   * resource group in the subscription is allowed.
+   */
+  allowedResourceGroups?: string[];
+};
+
 export type CleanupPolicy = "leave-running" | "stop-if-started";
 
 export type VpnPrerequisite = {
@@ -206,6 +222,8 @@ export type AgentToolsConfig = {
   $schema?: string;
   /** Named Azure DevOps profiles. e.g. { default: { organization: "...", defaultProject: "..." } } */
   azure?: Record<string, AzureConfig>;
+  /** Named Azure platform profiles. e.g. { default: { subscription: "..." } } */
+  azurePlatform?: Record<string, AzurePlatformConfig>;
   /** Named VPN definitions referenced by profile prerequisites. */
   vpns?: Record<string, VpnConfig>;
   /** Named Kubernetes cluster profiles. e.g. { default: {...}, staging: {...} } */

package/src/credential-guard/index.ts

@@ -173,6 +173,11 @@ const DEFAULT_BLOCKED_CLI_TOOLS: BlockedCliTool[] = [
     name: "psql",
     wrapper: "agent-tools-db",
   },
+  {
+    pattern: /(?:^|[;&|]\s*)az\s+(?:devops|pipelines|repos|boards|artifacts)\b/,
+    name: "az (Azure DevOps)",
+    wrapper: "agent-tools-azdo",
+  },
   {
     pattern: /(?:^|[;&|]\s*)az\s/,
     name: "az",
@@ -181,7 +186,7 @@ const DEFAULT_BLOCKED_CLI_TOOLS: BlockedCliTool[] = [
   {
     pattern: /(?:^|[;&|]\s*)curl\s.*dev\.azure\.com/,
     name: "curl (Azure DevOps)",
-    wrapper: "agent-tools-az",
+    wrapper: "agent-tools-azdo",
   },
 ];
 
@@ -209,7 +214,7 @@ const DEFAULT_POLLING_DETECTION_RULES: PollingDetectionRule[] = [
   },
   {
     pattern: /\bpipelines?\s+runs?\b/,
-    suggestion: "bun agent-tools-az build summary --build-id <ID>",
+    suggestion: "bun agent-tools-azdo build summary --build-id <ID>",
   },
 ];
 

package/src/gh-tool/errors.ts

@@ -34,7 +34,13 @@ export class GitHubAuthError extends Schema.TaggedError<GitHubAuthError>()("GitH
 
 export class GitHubMergeError extends Schema.TaggedError<GitHubMergeError>()("GitHubMergeError", {
   message: Schema.String,
-  reason: Schema.Literals(["conflicts", "checks_failing", "branch_protected", "unknown"]),
+  reason: Schema.Literals([
+    "conflicts",
+    "checks_failing",
+    "branch_protected",
+    "merge_queue",
+    "unknown",
+  ]),
   hint: Schema.optionalKey(Schema.String),
   nextCommand: Schema.optionalKey(Schema.String),
   retryable: Schema.optionalKey(Schema.Boolean),