@blogic-cz/agent-tools 0.18.1 → 1.0.0

package/src/azdo-tool/errors.ts

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+
+export class AzdoSecurityError extends Schema.TaggedError<AzdoSecurityError>()(
+  "AzdoSecurityError",
+  {
+    message: Schema.String,
+    command: Schema.String,
+    hint: Schema.optionalKey(Schema.String),
+    nextCommand: Schema.optionalKey(Schema.String),
+    retryable: Schema.optionalKey(Schema.Boolean),
+  },
+) {}
+
+export class AzdoCommandError extends Schema.TaggedError<AzdoCommandError>()("AzdoCommandError", {
+  message: Schema.String,
+  command: Schema.String,
+  exitCode: Schema.optionalKey(Schema.Number),
+  stderr: Schema.optionalKey(Schema.String),
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
+}) {}
+
+export class AzdoTimeoutError extends Schema.TaggedError<AzdoTimeoutError>()("AzdoTimeoutError", {
+  message: Schema.String,
+  command: Schema.String,
+  timeoutMs: Schema.Number,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
+}) {}
+
+export class AzdoParseError extends Schema.TaggedError<AzdoParseError>()("AzdoParseError", {
+  message: Schema.String,
+  rawOutput: Schema.String,
+  hint: Schema.optionalKey(Schema.String),
+  nextCommand: Schema.optionalKey(Schema.String),
+  retryable: Schema.optionalKey(Schema.Boolean),
+}) {}
+
+export type AzdoError = AzdoSecurityError | AzdoCommandError | AzdoTimeoutError | AzdoParseError;

package/src/azdo-tool/index.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+import { Command, Flag } from "effect/unstable/cli";
+import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { Effect, Layer, Option } from "effect";
+
+import {
+  makeSchemaCommand,
+  formatAny,
+  formatOption,
+  formatOutput,
+  logText,
+  renderCauseToStderr,
+  VERSION,
+} from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
+import {
+  findFailedJobs,
+  getBuildJobSummary,
+  getBuildLogContent,
+  getBuildLogs,
+  getBuildTimeline,
+} from "./build";
+import { AzdoService, AzdoServiceLayer } from "./service";
+import { ConfigServiceLayer } from "#config";
+
+// ---------------------------------------------------------------------------
+// Common flags shared across build subcommands
+// ---------------------------------------------------------------------------
+
+const commonBuildFlags = {
+  format: formatOption,
+  profile: Flag.optional(Flag.string("profile")).pipe(
+    Flag.withDescription("Azure DevOps profile name (from agent-tools config)"),
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Build subcommands
+// ---------------------------------------------------------------------------
+
+const buildTimelineCommand = Command.make(
+  "timeline",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const result = yield* getBuildTimeline(buildId);
+      yield* logText(formatAny(result, format));
+    }),
+).pipe(Command.withDescription("Get build timeline with all records (jobs, stages, tasks)"));
+
+const buildFailedJobsCommand = Command.make(
+  "failed-jobs",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const failedJobs = yield* findFailedJobs(buildId);
+      yield* logText(formatAny({ buildId, failedJobs }, format));
+    }),
+).pipe(Command.withDescription("Find failed or canceled jobs in a build"));
+
+const buildLogsCommand = Command.make(
+  "logs",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const result = yield* getBuildLogs(buildId);
+      yield* logText(formatAny(result, format));
+    }),
+).pipe(Command.withDescription("Get list of build logs"));
+
+const buildLogContentCommand = Command.make(
+  "log-content",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+    logId: Flag.integer("log-id").pipe(Flag.withDescription("Log ID")),
+  },
+  ({ buildId, format, logId, profile: _profile }) =>
+    Effect.gen(function* () {
+      const content = yield* getBuildLogContent(buildId, logId);
+      yield* logText(formatAny({ buildId, logId, content }, format));
+    }),
+).pipe(Command.withDescription("Get specific log content by log ID"));
+
+const buildSummaryCommand = Command.make(
+  "summary",
+  {
+    ...commonBuildFlags,
+    buildId: Flag.integer("build-id").pipe(Flag.withDescription("Build ID")),
+  },
+  ({ buildId, format, profile: _profile }) =>
+    Effect.gen(function* () {
+      const summary = yield* getBuildJobSummary(buildId);
+      yield* logText(formatAny({ buildId, summary }, format));
+    }),
+).pipe(Command.withDescription("Get job summaries with duration and status information"));
+
+// ---------------------------------------------------------------------------
+// Build parent command
+// ---------------------------------------------------------------------------
+
+const buildCommand = Command.make("build", {}).pipe(
+  Command.withDescription("Build helpers for Azure DevOps pipelines"),
+  Command.withSubcommands([
+    buildTimelineCommand,
+    buildFailedJobsCommand,
+    buildLogsCommand,
+    buildLogContentCommand,
+    buildSummaryCommand,
+  ]),
+);
+
+// ---------------------------------------------------------------------------
+// Raw command subcommand (preserves existing --cmd behavior)
+// ---------------------------------------------------------------------------
+
+const cmdCommand = Command.make(
+  "cmd",
+  {
+    profile: Flag.optional(Flag.string("profile")).pipe(
+      Flag.withDescription("Azure DevOps profile name (from agent-tools config)"),
+    ),
+    project: Flag.optional(Flag.string("project")).pipe(
+      Flag.withDescription("Azure DevOps project name (overrides config default)"),
+    ),
+    cmd: Flag.string("cmd").pipe(Flag.withDescription("az command (without 'az' prefix)")),
+    dryRun: Flag.boolean("dry-run").pipe(
+      Flag.withDescription("Show command without executing"),
+      Flag.withDefault(false),
+    ),
+    format: formatOption,
+  },
+  ({ profile: _profile, project, cmd, dryRun, format }) =>
+    Effect.gen(function* () {
+      const projectName = project ? Option.getOrUndefined(project) : undefined;
+
+      if (dryRun) {
+        const fullCommand = `az ${cmd}`;
+        yield* logText(`[DRY-RUN] Would execute: ${fullCommand}`);
+        return;
+      }
+
+      const az = yield* AzdoService;
+
+      const startTime = Date.now();
+      const output = yield* az.runCommand(cmd, projectName);
+      const executionTimeMs = Date.now() - startTime;
+
+      yield* logText(
+        formatOutput(
+          {
+            success: true,
+            data: output,
+            executionTimeMs,
+          },
+          format,
+        ),
+      );
+    }),
+).pipe(
+  Command.withDescription(
+    `Execute raw az CLI commands directly.
+
+EXAMPLES:
+  agent-tools-azdo cmd --cmd "pipelines list"
+  agent-tools-azdo cmd --cmd "repos list" --project my-project
+  agent-tools-azdo cmd --cmd "pipelines runs list --output json"`,
+  ),
+);
+
+// ---------------------------------------------------------------------------
+// Main command with subcommands
+// ---------------------------------------------------------------------------
+
+const commandsCommand = makeSchemaCommand(() => mainCommand);
+
+const mainCommand = Command.make("azdo-tool", {}).pipe(
+  Command.withDescription(
+    `Azure DevOps Tool for Coding Agents (READ-ONLY)
+
+For Azure platform (PaaS) resources — vm, webapp, storage, aks, keyvault — use az-tool instead.
+
+Typed build subcommands:
+  azdo-tool build timeline --build-id 123
+  azdo-tool build failed-jobs --build-id 123
+  azdo-tool build logs --build-id 123
+  azdo-tool build log-content --build-id 123 --log-id 45
+  azdo-tool build summary --build-id 123
+
+Raw az wrapper:
+  azdo-tool cmd --cmd "pipelines list"`,
+  ),
+  Command.withSubcommands([buildCommand, cmdCommand, commandsCommand]),
+);
+
+const cli = Command.run(mainCommand, {
+  version: VERSION,
+});
+
+const MainLayer = AzdoServiceLayer.pipe(
+  Layer.provideMerge(ConfigServiceLayer),
+  Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
+);
+
+const program = withAudit("azdo", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
+
+BunRuntime.runMain(program, {
+  disableErrorReporting: true,
+});

package/src/azdo-tool/security.ts

@@ -0,0 +1,157 @@
+import type { InvokeParams, SecurityCheckResult } from "./types";
+
+import {
+  ALLOWED_SUBCOMMANDS,
+  BLOCKED_SUBCOMMANDS,
+  ALLOWED_INVOKE_AREAS,
+  ALLOWED_INVOKE_RESOURCES,
+  BLOCKED_INVOKE_AREAS,
+  BLOCKED_INVOKE_RESOURCES,
+  STANDALONE_AZ_COMMANDS,
+} from "./config";
+import { extractOptionValue } from "./extract-option-value";
+import { isCredentialBlockedSegment, isCredentialBlockedVerb } from "#shared/azure-credentials";
+
+export function isCommandAllowed(cmd: string): SecurityCheckResult {
+  const rawCommandWords = cmd.trim().split(/\s+/);
+  const commandWords = cmd
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((w) => !w.startsWith("-"));
+
+  if (commandWords.includes("invoke")) {
+    const area = extractOptionValue(rawCommandWords, "--area");
+    const resource = extractOptionValue(rawCommandWords, "--resource");
+
+    if (!area || !resource) {
+      return {
+        allowed: false,
+        command: cmd,
+        reason: "Invoke command requires both --area and --resource options.",
+      };
+    }
+
+    const method = extractOptionValue(rawCommandWords, "--http-method");
+
+    if (method && method.toLowerCase() !== "get") {
+      return {
+        allowed: false,
+        command: cmd,
+        reason: "Invoke command only allows read-only HTTP method GET.",
+      };
+    }
+
+    const invokeSecurityCheck = isInvokeAllowed({
+      area: area.toLowerCase(),
+      resource: resource.toLowerCase(),
+    });
+
+    if (!invokeSecurityCheck.allowed) {
+      return {
+        allowed: false,
+        command: cmd,
+        reason: invokeSecurityCheck.reason,
+      };
+    }
+
+    return { allowed: true, command: cmd };
+  }
+
+  // The acr/account groups run against the Azure platform rather than Azure
+  // DevOps, so the platform credential rules apply to them here too. Without
+  // this, `acr credential show` passes the DevOps verb check and prints the
+  // registry's admin password. Matched across every word rather than
+  // positionally: stricter than az-tool's parse, which suits a legacy
+  // passthrough.
+  const standaloneGroup = commandWords[0];
+  if (
+    standaloneGroup &&
+    STANDALONE_AZ_COMMANDS.includes(standaloneGroup as (typeof STANDALONE_AZ_COMMANDS)[number])
+  ) {
+    const credentialWord = commandWords.find(
+      (word) => isCredentialBlockedVerb(word) || isCredentialBlockedSegment(word),
+    );
+
+    if (credentialWord) {
+      return {
+        allowed: false,
+        command: cmd,
+        reason: `'${credentialWord}' addresses credential material and is blocked.`,
+      };
+    }
+  }
+
+  const blockedWord = commandWords.find((word) =>
+    BLOCKED_SUBCOMMANDS.includes(word as (typeof BLOCKED_SUBCOMMANDS)[number]),
+  );
+
+  if (blockedWord) {
+    return {
+      allowed: false,
+      command: cmd,
+      reason: `Command contains blocked operation '${blockedWord}'. Only read-only operations allowed: ${ALLOWED_SUBCOMMANDS.join(", ")}`,
+    };
+  }
+
+  const allowedOperationIndex = commandWords.findIndex((word) =>
+    ALLOWED_SUBCOMMANDS.includes(word as (typeof ALLOWED_SUBCOMMANDS)[number]),
+  );
+
+  if (allowedOperationIndex === -1) {
+    return {
+      allowed: false,
+      command: cmd,
+      reason: `Command must contain a read-only operation: ${ALLOWED_SUBCOMMANDS.join(", ")}. Example: "pipelines list", "repos show --id 123"`,
+    };
+  }
+
+  // "run" is read-only only as `az pipelines run`. On the standalone groups it
+  // executes code in Azure (`az acr run`, `az acr task run`), so it is rejected
+  // anywhere other than the pipelines group.
+  if (commandWords[allowedOperationIndex] === "run" && commandWords[0] !== "pipelines") {
+    return {
+      allowed: false,
+      command: cmd,
+      reason: `'run' is only allowed as 'pipelines run'. Outside the pipelines group it executes commands in Azure.`,
+    };
+  }
+
+  return { allowed: true, command: cmd };
+}
+
+export function isInvokeAllowed(params: InvokeParams): SecurityCheckResult {
+  const { area, resource } = params;
+
+  if (BLOCKED_INVOKE_AREAS.includes(area as (typeof BLOCKED_INVOKE_AREAS)[number])) {
+    return {
+      allowed: false,
+      reason: `Area '${area}' is blocked. Dangerous areas not allowed: ${BLOCKED_INVOKE_AREAS.join(", ")}`,
+    };
+  }
+
+  if (!ALLOWED_INVOKE_AREAS.includes(area as (typeof ALLOWED_INVOKE_AREAS)[number])) {
+    return {
+      allowed: false,
+      reason: `Area '${area}' is not in allowed list. Allowed areas: ${ALLOWED_INVOKE_AREAS.join(", ")}`,
+    };
+  }
+
+  const blockedResources = BLOCKED_INVOKE_RESOURCES[area];
+  if (blockedResources?.includes(resource)) {
+    return {
+      allowed: false,
+      reason: `Resource '${resource}' in area '${area}' is blocked. Write resources not allowed.`,
+    };
+  }
+
+  const allowedResources = ALLOWED_INVOKE_RESOURCES[area];
+  if (!allowedResources?.includes(resource)) {
+    return {
+      allowed: false,
+      reason: `Resource '${resource}' is not in allowed list for area '${area}'. Allowed resources: ${allowedResources?.join(", ") ?? "none"}`,
+    };
+  }
+
+  return { allowed: true };
+}