@blogic-cz/agent-tools 0.5.6 → 0.6.0

package/README.md

@@ -27,6 +27,25 @@ These tools wrap each CLI with:
 bun add -d @blogic-cz/agent-tools
 ```
 
+### Skill installation
+
+Install per-tool skills for only the tools your project uses:
+
+```bash
+npx skills add blogic-cz/agent-tools --path skill/gh-tool
+npx skills add blogic-cz/agent-tools --path skill/db-tool
+npx skills add blogic-cz/agent-tools --path skill/k8s-tool
+npx skills add blogic-cz/agent-tools --path skill/az-tool
+npx skills add blogic-cz/agent-tools --path skill/logs-tool
+npx skills add blogic-cz/agent-tools --path skill/session-tool
+```
+
+Or install the all-in-one skill that covers every tool:
+
+```bash
+npx skills add blogic-cz/agent-tools --path skill/agent-tools
+```
+
 **Requirements:** [Bun](https://bun.sh/) >=1.0.0
 
 ### For agents reading this
@@ -41,8 +60,8 @@ Follow these steps to set up agent-tools in the consumer project.
   ```
 - **Non-JavaScript project** (no `package.json`): Skip installation — run tools directly with `bunx`:
   ```bash
-  bunx agent-tools-gh pr status
-  bunx agent-tools-k8s pods --env test
+  bunx gh-tool pr status
+  bunx k8s-tool pods --env test
   ```
 
 **Step 2 — Configure**
@@ -68,32 +87,54 @@ Set up the credential guard for the agent's platform:
 
 For each tool the user selected in Step 2:
 
-1. Run `bunx agent-tools-<tool> --help` to verify it works
+1. Run `bun <tool-name> --help` to verify it works (e.g. `bun gh-tool --help`)
 2. Summarize the key commands available
 3. Show the user what data they have access to based on their `agent-tools.json5` — e.g. which environments, clusters, namespaces, databases, or profiles are configured and reachable
 
 **Step 5 — Skill & Agent Docs**
 
-Tell the user to run the following command themselves — it's interactive and lets them choose which agents to install the skill for:
+Install **only the per-tool skills the project needs** (recommended), or the all-in-one skill:
 
 ```bash
-npx skills add blogic-cz/agent-tools
+# Per-tool skills (recommended) — install only what the project uses
+npx skills add blogic-cz/agent-tools --path skill/gh-tool
+npx skills add blogic-cz/agent-tools --path skill/db-tool
+npx skills add blogic-cz/agent-tools --path skill/k8s-tool
+npx skills add blogic-cz/agent-tools --path skill/az-tool
+npx skills add blogic-cz/agent-tools --path skill/logs-tool
+npx skills add blogic-cz/agent-tools --path skill/session-tool
+
+# All-in-one skill (alternative) — all tools in a single skill
+npx skills add blogic-cz/agent-tools --path skill/agent-tools
 ```
 
-**Do not run this command for the user** — it requires interactive selection.
+**Do not run these commands for the user** — they require interactive selection.
+
+Available per-tool skills:
+
+| Skill          | Install when project uses                  |
+| -------------- | ------------------------------------------ |
+| `gh-tool`      | GitHub PRs, issues, workflows, CI checks   |
+| `db-tool`      | SQL queries, schema introspection          |
+| `k8s-tool`     | Kubernetes pods, logs, deployments         |
+| `az-tool`      | Azure DevOps pipelines, builds             |
+| `logs-tool`    | Application log reading (local and remote) |
+| `session-tool` | OpenCode session history browsing          |
+| `agent-tools`  | All of the above in a single skill         |
 
 Then update the project's `AGENTS.md` and/or `CLAUDE.md`:
 
-1. Add an `agent-tools` row to the skills table (if one exists):
+1. Add rows to the skills table for each installed skill (if one exists):
    ```markdown
-   | Agent wrapper tools (`db-tool`, `k8s-tool`, `logs-tool`, `az-tool`, `gh` patterns) | `agent-tools` |
+   | GitHub PRs, issues, workflows | `gh-tool` |
+   | Database queries, schema | `db-tool` |
    ```
 2. Add or update the **Tooling** section:
 
    ```markdown
    ## Tooling
 
-   For tool wrappers and operational patterns, load `agent-tools`.
+   For tool wrappers and operational patterns, load the relevant tool skill (`gh-tool`, `db-tool`, etc.).
    ```
 
 **Step 6 — Custom Tool Scaffold**
@@ -146,34 +187,17 @@ bun run agent-tools/example-tool/index.ts ping
 3. Run tools:
 
 ```bash
-bunx agent-tools-gh pr status
-bunx agent-tools-k8s kubectl --env test --cmd "get pods"
-bunx agent-tools-logs list --env local
-bunx agent-tools-audit list --limit 20
+bun gh-tool pr status
+bun k8s-tool kubectl --env test --cmd "get pods"
+bun logs-tool list --env local
+bun audit-tool list --limit 20
 ```
 
 ```bash
-bunx agent-tools-gh pr review-triage   # interactive summary of PR feedback
-bunx agent-tools-k8s pods --env test   # list pods (structured command)
+bun gh-tool pr review-triage   # interactive summary of PR feedback
+bun k8s-tool pods --env test   # list pods (structured command)
 ```
 
-Optionally, add script aliases to your `package.json` for shorter invocation:
-
-```json
-{
-  "scripts": {
-    "gh-tool": "agent-tools-gh",
-    "audit-tool": "agent-tools-audit",
-    "k8s-tool": "agent-tools-k8s",
-    "db-tool": "agent-tools-db",
-    "logs-tool": "agent-tools-logs",
-    "session-tool": "agent-tools-session"
-  }
-}
-```
-
-Then run via `bun run k8s-tool -- pods --env test` instead of `bunx agent-tools-k8s pods --env test`.
-
 4. Hook up the credential guard in your agent config (Claude Code, OpenCode, etc.):
 
 ```typescript
@@ -184,19 +208,19 @@ export default { handleToolExecuteBefore };
 
 ## Tools
 
-| Binary                | Description                                                                                                      |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `agent-tools-gh`      | GitHub CLI wrapper — PR management, issues, workflows, composite commands (`review-triage`, `reply-and-resolve`) |
-| `agent-tools-audit`   | Audit trail browser — inspect recent tool invocations and purge old entries                                      |
-| `agent-tools-db`      | Database query tool — SQL execution, schema introspection                                                        |
-| `agent-tools-k8s`     | Kubernetes tool — kubectl wrapper + structured commands (`pods`, `logs`, `describe`, `exec`, `top`)              |
-| `agent-tools-az`      | Azure DevOps tool — pipelines, builds, repos                                                                     |
-| `agent-tools-logs`    | Application logs — read local and remote (k8s pod) logs                                                          |
-| `agent-tools-session` | OpenCode session browser — list, read, search sessions                                                           |
+| Binary         | Description                                                                                                      |
+| -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `gh-tool`      | GitHub CLI wrapper — PR management, issues, workflows, composite commands (`review-triage`, `reply-and-resolve`) |
+| `audit-tool`   | Audit trail browser — inspect recent tool invocations and purge old entries                                      |
+| `db-tool`      | Database query tool — SQL execution, schema introspection                                                        |
+| `k8s-tool`     | Kubernetes tool — kubectl wrapper + structured commands (`pods`, `logs`, `describe`, `exec`, `top`)              |
+| `az-tool`      | Azure DevOps tool — pipelines, builds, repos                                                                     |
+| `logs-tool`    | Application logs — read local and remote (k8s pod) logs                                                          |
+| `session-tool` | OpenCode session browser — list, read, search sessions                                                           |
 
-All tools support `--help` for full usage documentation.
+All tools support `--help` for full usage documentation. Legacy `agent-tools-*` binary names (e.g. `agent-tools-gh`) still work for backwards compatibility.
 
-`agent-tools-audit` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
+`audit-tool` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
 
 ## Audit Logging
 
@@ -212,19 +236,19 @@ Entries older than `retentionDays` (default: 90) are automatically purged on eac
 
 ```bash
 # Recent 20 entries (default)
-bunx agent-tools-audit list
+bun audit-tool list
 
 # Last 50 entries, JSON format
-bunx agent-tools-audit list --limit 50 --format json
+bun audit-tool list --limit 50 --format json
 
 # Filter by tool
-bunx agent-tools-audit list --tool gh
+bun audit-tool list --tool gh
 
 # Filter by project directory
-bunx agent-tools-audit list --project /Users/me/my-repo
+bun audit-tool list --project /Users/me/my-repo
 
 # Purge entries older than 30 days
-bunx agent-tools-audit purge --days 30
+bun audit-tool purge --days 30
 ```
 
 ### Audit Configuration
@@ -293,8 +317,8 @@ Each tool section supports multiple named profiles. Select with `--profile <name
 ```
 
 ```bash
-bunx agent-tools-az cmd --cmd "pipelines list"                    # uses "default" profile
-bunx agent-tools-az cmd --cmd "pipelines list" --profile legacy   # uses "legacy" profile
+bun az-tool cmd --cmd "pipelines list"                    # uses "default" profile
+bun az-tool cmd --cmd "pipelines list" --profile legacy   # uses "legacy" profile
 ```
 
 **Profile resolution:** `--profile` flag > auto-select (single profile) > `"default"` key > error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.5.6",
+  "version": "0.6.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",
@@ -25,7 +25,14 @@
     "agent-tools-gh": "./src/gh-tool/index.ts",
     "agent-tools-k8s": "./src/k8s-tool/index.ts",
     "agent-tools-logs": "./src/logs-tool/index.ts",
-    "agent-tools-session": "./src/session-tool/index.ts"
+    "agent-tools-session": "./src/session-tool/index.ts",
+    "audit-tool": "./src/audit-tool/index.ts",
+    "az-tool": "./src/az-tool/index.ts",
+    "db-tool": "./src/db-tool/index.ts",
+    "gh-tool": "./src/gh-tool/index.ts",
+    "k8s-tool": "./src/k8s-tool/index.ts",
+    "logs-tool": "./src/logs-tool/index.ts",
+    "session-tool": "./src/session-tool/index.ts"
   },
   "files": [
     "src/",

package/src/credential-guard/index.ts

@@ -45,6 +45,7 @@ export type CredentialGuard = {
   isDangerousBashCommand: (command: string) => boolean;
   getBlockedCliTool: (command: string) => { name: string; wrapper: string } | null;
   isGhCommandAllowed: (command: string) => boolean;
+  detectSleepPolling: (command: string) => string | null;
 };
 
 // ============================================================================
@@ -184,6 +185,34 @@ const DEFAULT_BLOCKED_CLI_TOOLS: BlockedCliTool[] = [
   },
 ];
 
+type PollingDetectionRule = {
+  pattern: RegExp;
+  suggestion: string;
+};
+
+const DEFAULT_POLLING_DETECTION_RULES: PollingDetectionRule[] = [
+  {
+    pattern: /workflow\s+(?:list|view|jobs|logs|job-logs)\b/,
+    suggestion: "bun agent-tools-gh workflow watch --run <ID>",
+  },
+  {
+    pattern: /pr\s+checks(?![\w-])(?!.*--watch)/,
+    suggestion: "bun agent-tools-gh pr checks --pr <N> --watch",
+  },
+  {
+    pattern: /pr\s+rerun-checks\b/,
+    suggestion: "bun agent-tools-gh pr checks --pr <N> --watch (after rerun completes)",
+  },
+  {
+    pattern: /kubectl\b/,
+    suggestion: 'bun agent-tools-k8s kubectl --env <env> --cmd "wait --for=condition=..."',
+  },
+  {
+    pattern: /\bpipelines?\s+runs?\b/,
+    suggestion: "bun agent-tools-az build summary --build-id <ID>",
+  },
+];
+
 /**
  * Read-only gh subcommands safe on external repos with -R flag.
  */
@@ -325,6 +354,17 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
     return ghSegments.every((segment) => isGhCommandAllowed(segment.trim()));
   }
 
+  function detectSleepPolling(command: string): string | null {
+    if (!/\bsleep\s+\d+/.test(command)) return null;
+
+    for (const { pattern, suggestion } of DEFAULT_POLLING_DETECTION_RULES) {
+      if (pattern.test(command)) {
+        return suggestion;
+      }
+    }
+    return null;
+  }
+
   function getBlockedCliTool(command: string): { name: string; wrapper: string } | null {
     for (const { pattern, name, wrapper } of blockedCliTools) {
       if (pattern.test(command)) {
@@ -390,6 +430,17 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
         );
       }
 
+      const sleepSuggestion = detectSleepPolling(command);
+      if (sleepSuggestion) {
+        throw new Error(
+          `\u{26A0}\u{FE0F} Sleep-polling detected.\n\n` +
+            `Instead of polling with sleep, use the built-in watch command:\n\n` +
+            `Use instead: ${sleepSuggestion}\n\n` +
+            `Watch commands block until completion — no polling needed.\n\n` +
+            `→ Skill "agent-tools"`,
+        );
+      }
+
       const blockedTool = getBlockedCliTool(command);
       if (blockedTool) {
         throw new Error(
@@ -412,6 +463,7 @@ export function createCredentialGuard(config?: CredentialGuardConfig): Credentia
     isDangerousBashCommand,
     getBlockedCliTool,
     isGhCommandAllowed,
+    detectSleepPolling,
   };
 }
 
@@ -441,3 +493,6 @@ export const getBlockedCliTool = defaultGuard.getBlockedCliTool;
 
 /** Check if a gh command is allowed (default guard). */
 export const isGhCommandAllowed = defaultGuard.isGhCommandAllowed;
+
+/** Detect sleep-polling with agent-tools wrapper commands (default guard). */
+export const detectSleepPolling = defaultGuard.detectSleepPolling;

package/src/gh-tool/index.ts

@@ -47,6 +47,7 @@ import {
 import { repoInfoCommand, repoListCommand, repoSearchCodeCommand } from "./repo";
 import { GitHubService } from "./service";
 import {
+  workflowAnnotationsCommand,
   workflowCancelCommand,
   workflowJobLogsCommand,
   workflowJobsCommand,
@@ -104,7 +105,7 @@ const repoCommand = Command.make("repo", {}).pipe(
 
 const workflowCommand = Command.make("workflow", {}).pipe(
   Command.withDescription(
-    "GitHub Actions workflow operations (list runs, view, jobs, logs, job-logs, rerun, cancel, watch)",
+    "GitHub Actions workflow operations (list runs, view, jobs, logs, job-logs, annotations, rerun, cancel, watch)",
   ),
   Command.withSubcommands([
     workflowListCommand,
@@ -112,6 +113,7 @@ const workflowCommand = Command.make("workflow", {}).pipe(
     workflowJobsCommand,
     workflowLogsCommand,
     workflowJobLogsCommand,
+    workflowAnnotationsCommand,
     workflowRerunCommand,
     workflowCancelCommand,
     workflowWatchCommand,
@@ -152,10 +154,11 @@ WORKFLOW FOR AI AGENTS:
   12. Use 'workflow view --run N' to inspect a specific run with jobs/steps
   13. Use 'workflow logs --run N' to get logs (failed jobs by default)
   14. Use 'workflow job-logs --run N --job "build-web-app"' to get clean parsed logs for a specific job
-  15. Use 'workflow watch --run N' to watch until completion
-  16. Use 'release status' to inspect latest release + repository context
-  17. Use 'release create --tag vX.Y.Z --generate-notes' to publish a release
-  18. Use 'release edit/view/list/delete' to maintain existing releases`,
+  15. Use 'workflow annotations --run N' to list CI annotations (errors, warnings, notices)
+  16. Use 'workflow watch --run N' to watch until completion
+  17. Use 'release status' to inspect latest release + repository context
+  18. Use 'release create --tag vX.Y.Z --generate-notes' to publish a release
+  19. Use 'release edit/view/list/delete' to maintain existing releases`,
   ),
   Command.withSubcommands([prCommand, issueCommand, repoCommand, workflowCommand, releaseCommand]),
 );

package/src/gh-tool/types.ts

@@ -96,3 +96,21 @@ export type PRStatusNone = {
 };
 
 export type PRStatusResult = PRStatusSingle | PRStatusMultiple | PRStatusNone;
+
+export type CheckRunAnnotation = {
+  path: string;
+  start_line: number;
+  end_line: number;
+  start_column: number | null;
+  end_column: number | null;
+  annotation_level: "notice" | "warning" | "failure";
+  title: string | null;
+  message: string;
+  raw_details: string | null;
+};
+
+export type JobAnnotations = {
+  jobId: number;
+  jobName: string;
+  annotations: CheckRunAnnotation[];
+};

package/src/gh-tool/workflow.ts

@@ -4,6 +4,7 @@ import { Console, Effect, Option } from "effect";
 import { formatOption, logFormatted } from "#shared";
 import { GitHubCommandError, GitHubNotFoundError } from "./errors";
 import { GitHubService } from "./service";
+import type { CheckRunAnnotation, JobAnnotations } from "./types";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -235,6 +236,69 @@ const watchRun = Effect.fn("workflow.watchRun")(function* (runId: number, repo:
   };
 });
 
+const fetchAnnotations = Effect.fn("workflow.fetchAnnotations")(function* (opts: {
+  runId: number;
+  job: string | null;
+  repo: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  let owner: string;
+  let repoName: string;
+  if (opts.repo !== null) {
+    const parts = opts.repo.split("/");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      return yield* new GitHubCommandError({
+        message: `Invalid --repo format: "${opts.repo}". Expected "owner/name" (e.g. "blogic-cz/agent-tools").`,
+        command: "workflow annotations",
+        exitCode: 1,
+        stderr: "",
+      });
+    }
+    owner = parts[0];
+    repoName = parts[1];
+  } else {
+    const info = yield* gh.getRepoInfo();
+    owner = info.owner;
+    repoName = info.name;
+  }
+
+  const jobs = yield* listJobs(opts.runId, opts.repo);
+
+  let targetJobs = jobs;
+  if (opts.job !== null) {
+    const jobId = yield* resolveJobId(opts.runId, opts.job, opts.repo);
+    targetJobs = jobs.filter((j) => j.databaseId === jobId);
+  }
+
+  const results: JobAnnotations[] = [];
+  for (const job of targetJobs) {
+    const annotations = yield* gh
+      .runGhJson<CheckRunAnnotation[]>([
+        "api",
+        `repos/${owner}/${repoName}/check-runs/${job.databaseId}/annotations`,
+        "--paginate",
+      ])
+      .pipe(
+        Effect.catchTag("GitHubCommandError", () => Effect.succeed([] as CheckRunAnnotation[])),
+      );
+
+    if (annotations.length > 0) {
+      results.push({
+        jobId: job.databaseId,
+        jobName: job.name,
+        annotations,
+      });
+    }
+  }
+
+  return {
+    runId: opts.runId,
+    totalAnnotations: results.reduce((sum, r) => sum + r.annotations.length, 0),
+    jobs: results,
+  };
+});
+
 // ---------------------------------------------------------------------------
 // Log parsing utilities (pure functions)
 // ---------------------------------------------------------------------------
@@ -605,3 +669,29 @@ export const workflowJobLogsCommand = Command.make(
     "Fetch parsed, clean logs for a specific job in a workflow run. Resolves job name to ID, strips timestamps/ANSI, groups by step.",
   ),
 );
+
+export const workflowAnnotationsCommand = Command.make(
+  "annotations",
+  {
+    format: formatOption,
+    job: Flag.string("job").pipe(
+      Flag.withDescription("Filter to a specific job name (exact or partial match)"),
+      Flag.optional,
+    ),
+    repo: repoOption,
+    run: Flag.integer("run").pipe(Flag.withDescription("Workflow run ID")),
+  },
+  ({ format, job, repo, run }) =>
+    Effect.gen(function* () {
+      const result = yield* fetchAnnotations({
+        runId: run,
+        job: Option.getOrNull(job),
+        repo: Option.getOrNull(repo),
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "List annotations (errors, warnings, notices) from check runs in a workflow run. Shows problem matcher output, test failures, and other CI annotations.",
+  ),
+);