@blogic-cz/agent-tools 0.2.7 → 0.4.0

package/README.md

@@ -15,10 +15,10 @@ These tools wrap each CLI with:
 
 ## Installation
 
-> **Recommended:** Copy the repo URL and tell your AI agent to install it. The agent will set up everything — dependencies, config file, credential guard — in the right places for your project.
+> **Recommended:** Copy the repo URL and tell your AI agent to install it. The agent will set up everything — dev dependency, config file, credential guard, skill — in the right places for your project.
 >
 > ```
-> Install @blogic-cz/agent-tools from https://github.com/blogic-cz/agent-tools and set it up for this project.
+> Install @blogic-cz/agent-tools from https://github.com/blogic-cz/agent-tools as a dev dependency, install the agent-tools skill, set up the credential guard, and configure the tools I need for this project.
 > ```
 
 ### Manual installation
@@ -31,11 +31,88 @@ bun add -d @blogic-cz/agent-tools
 
 ### For agents reading this
 
-Clone the repo and look at the source. The tools are in `src/`, each tool is self-contained:
+Follow these steps to set up agent-tools in the consumer project.
+
+**Step 1 — Install**
+
+- **JavaScript/TypeScript project** (has `package.json`): Install as a **dev dependency**:
+  ```bash
+  bun add -d @blogic-cz/agent-tools
+  ```
+- **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
+  ```
+
+**Step 2 — Configure**
+
+Ask the user which tools they need (gh, db, k8s, az, logs, session). Create `agent-tools.json5` in the project root with **only the selected tools configured**. See [`examples/agent-tools.json5`](./examples/agent-tools.json5) for the full config reference with all options documented.
+
+Minimal starting config:
+
+```json5
+{
+  $schema: "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+}
+```
+
+**Step 3 — Credential Guard**
+
+Set up the credential guard for the agent's platform:
+
+- **Claude Code**: Add the `PreToolUse` hook to `.claude/settings.json` — see [Setup for Claude Code](#setup-for-claude-code)
+- **OpenCode**: Create the plugin at `.opencode/plugins/credential-guard.ts` — see [Setup for OpenCode](#setup-for-opencode)
+
+**Step 4 — Test & Demo**
+
+For each tool the user selected in Step 2:
+
+1. Run `bunx agent-tools-<tool> --help` to verify it works
+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:
+
+```bash
+npx skills add blogic-cz/agent-tools
+```
+
+**Do not run this command for the user** — it requires interactive selection.
+
+Then update the project's `AGENTS.md` and/or `CLAUDE.md`:
+
+1. Add an `agent-tools` row to the skills table (if one exists):
+   ```markdown
+   | Agent wrapper tools (`db-tool`, `k8s-tool`, `logs-tool`, `az-tool`, `gh` patterns) | `agent-tools` |
+   ```
+2. Add or update the **Tooling** section:
+
+   ```markdown
+   ## Tooling
+
+   For tool wrappers and operational patterns, load `agent-tools`.
+   ```
+
+**Step 6 — Custom Tool Scaffold**
+
+Create an `agent-tools/` directory in the project root with an example tool so the user has a working template for building project-specific tools. Copy the scaffold from [`examples/custom-tool/`](./examples/custom-tool/):
+
+```
+agent-tools/
+  package.json          # private package depending on @blogic-cz/agent-tools
+  tsconfig.json         # extends root tsconfig
+  noop.ts               # placeholder export for typecheck
+  example-tool/
+    index.ts             # ping-pong example using Effect CLI
+```
+
+After creating the files, run `bun install` in the `agent-tools/` directory (or from the workspace root if it's a monorepo). Then verify:
 
 ```bash
-git clone https://github.com/blogic-cz/agent-tools.git
-ls src/  # gh-tool/ db-tool/ k8s-tool/ az-tool/ logs-tool/ session-tool/ credential-guard/
+bun run agent-tools/example-tool/index.ts ping
 ```
 
 ## Quick Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, and sessions",
   "keywords": [
     "agent",

package/src/gh-tool/index.ts

@@ -5,12 +5,13 @@ import { Effect, Layer } from "effect";
 
 import { renderCauseToStderr, VERSION } from "#shared";
 import {
-  issueListCommand,
-  issueViewCommand,
   issueCloseCommand,
-  issueReopenCommand,
   issueCommentCommand,
   issueEditCommand,
+  issueListCommand,
+  issueReopenCommand,
+  issueTriageSummaryCommand,
+  issueViewCommand,
 } from "./issue";
 import {
   prViewCommand,
@@ -33,6 +34,14 @@ import {
   prReplyAndResolveCommand,
   prReviewTriageCommand,
 } from "./pr/index";
+import {
+  releaseCreateCommand,
+  releaseDeleteCommand,
+  releaseEditCommand,
+  releaseListCommand,
+  releaseStatusCommand,
+  releaseViewCommand,
+} from "./release";
 import { repoInfoCommand, repoListCommand, repoSearchCodeCommand } from "./repo";
 import { GitHubService } from "./service";
 import {
@@ -72,7 +81,9 @@ const prCommand = Command.make("pr", {}).pipe(
 );
 
 const issueCommand = Command.make("issue", {}).pipe(
-  Command.withDescription("Issue operations (list, view, close, reopen, comment, edit)"),
+  Command.withDescription(
+    "Issue operations (list, view, close, reopen, comment, edit, triage-summary)",
+  ),
   Command.withSubcommands([
     issueListCommand,
     issueViewCommand,
@@ -80,6 +91,7 @@ const issueCommand = Command.make("issue", {}).pipe(
     issueReopenCommand,
     issueCommentCommand,
     issueEditCommand,
+    issueTriageSummaryCommand,
   ]),
 );
 
@@ -104,6 +116,18 @@ const workflowCommand = Command.make("workflow", {}).pipe(
   ]),
 );
 
+const releaseCommand = Command.make("release", {}).pipe(
+  Command.withDescription("Release operations (create, list, view, edit, delete, status)"),
+  Command.withSubcommands([
+    releaseCreateCommand,
+    releaseListCommand,
+    releaseViewCommand,
+    releaseEditCommand,
+    releaseDeleteCommand,
+    releaseStatusCommand,
+  ]),
+);
+
 const mainCommand = Command.make("gh-tool", {}).pipe(
   Command.withDescription(
     `GitHub CLI Tool for Coding Agents
@@ -126,9 +150,12 @@ 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`,
+  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`,
   ),
-  Command.withSubcommands([prCommand, issueCommand, repoCommand, workflowCommand]),
+  Command.withSubcommands([prCommand, issueCommand, repoCommand, workflowCommand, releaseCommand]),
 );
 
 const cli = Command.run(mainCommand, {

package/src/gh-tool/issue/commands.ts

@@ -0,0 +1,145 @@
+import { Command, Flag } from "effect/unstable/cli";
+import { Effect, Option } from "effect";
+
+import { formatOption, logFormatted } from "#shared";
+
+import { closeIssue, commentOnIssue, editIssue, listIssues, reopenIssue, viewIssue } from "./core";
+
+export const issueListCommand = Command.make(
+  "list",
+  {
+    format: formatOption,
+    labels: Flag.string("labels").pipe(
+      Flag.withDescription("Filter by label (comma-separated)"),
+      Flag.optional,
+    ),
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Maximum number of issues to return"),
+      Flag.withDefault(30),
+    ),
+    state: Flag.choice("state", ["open", "closed", "all"]).pipe(
+      Flag.withDescription("Filter by state: open, closed, all"),
+      Flag.withDefault("open"),
+    ),
+  },
+  ({ format, labels, limit, state }) =>
+    Effect.gen(function* () {
+      const issues = yield* listIssues({
+        labels: Option.getOrNull(labels),
+        limit,
+        state,
+      });
+      yield* logFormatted(issues, format);
+    }),
+).pipe(Command.withDescription("List issues (default: open, use --state to filter)"));
+
+export const issueViewCommand = Command.make(
+  "view",
+  {
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number")),
+  },
+  ({ format, issue }) =>
+    Effect.gen(function* () {
+      const info = yield* viewIssue(issue);
+      yield* logFormatted(info, format);
+    }),
+).pipe(Command.withDescription("View issue details"));
+
+export const issueCloseCommand = Command.make(
+  "close",
+  {
+    comment: Flag.string("comment").pipe(
+      Flag.withDescription("Comment to add when closing"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to close")),
+    reason: Flag.choice("reason", ["completed", "not planned"]).pipe(
+      Flag.withDescription("Close reason: completed, not planned"),
+      Flag.withDefault("completed"),
+    ),
+  },
+  ({ comment, format, issue, reason }) =>
+    Effect.gen(function* () {
+      const result = yield* closeIssue({
+        comment: Option.getOrNull(comment),
+        issue,
+        reason,
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Close an issue with optional comment and reason"));
+
+export const issueReopenCommand = Command.make(
+  "reopen",
+  {
+    comment: Flag.string("comment").pipe(
+      Flag.withDescription("Comment to add when reopening"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to reopen")),
+  },
+  ({ comment, format, issue }) =>
+    Effect.gen(function* () {
+      const result = yield* reopenIssue({
+        comment: Option.getOrNull(comment),
+        issue,
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Reopen a closed issue"));
+
+export const issueCommentCommand = Command.make(
+  "comment",
+  {
+    body: Flag.string("body").pipe(Flag.withDescription("Comment body text")),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to comment on")),
+  },
+  ({ body, format, issue }) =>
+    Effect.gen(function* () {
+      const result = yield* commentOnIssue({ body, issue });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Post a comment on an issue"));
+
+export const issueEditCommand = Command.make(
+  "edit",
+  {
+    addAssignee: Flag.string("add-assignee").pipe(
+      Flag.withDescription("Add assignee login (comma-separated for multiple)"),
+      Flag.optional,
+    ),
+    addLabels: Flag.string("add-labels").pipe(
+      Flag.withDescription("Add labels (comma-separated)"),
+      Flag.optional,
+    ),
+    body: Flag.string("body").pipe(Flag.withDescription("New issue body"), Flag.optional),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to edit")),
+    removeAssignee: Flag.string("remove-assignee").pipe(
+      Flag.withDescription("Remove assignee login (comma-separated for multiple)"),
+      Flag.optional,
+    ),
+    removeLabels: Flag.string("remove-labels").pipe(
+      Flag.withDescription("Remove labels (comma-separated)"),
+      Flag.optional,
+    ),
+    title: Flag.string("title").pipe(Flag.withDescription("New issue title"), Flag.optional),
+  },
+  ({ addAssignee, addLabels, body, format, issue, removeAssignee, removeLabels, title }) =>
+    Effect.gen(function* () {
+      const result = yield* editIssue({
+        addAssignee: Option.getOrNull(addAssignee),
+        addLabels: Option.getOrNull(addLabels),
+        body: Option.getOrNull(body),
+        issue,
+        removeAssignee: Option.getOrNull(removeAssignee),
+        removeLabels: Option.getOrNull(removeLabels),
+        title: Option.getOrNull(title),
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Edit issue title, body, labels, or assignees"));

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

@@ -0,0 +1,208 @@
+import { Effect } from "effect";
+
+import { GitHubCommandError } from "#gh/errors";
+import { GitHubService } from "#gh/service";
+
+export type IssueInfo = {
+  number: number;
+  title: string;
+  state: string;
+  url: string;
+  labels: Array<{ name: string }>;
+  assignees: Array<{ login: string }>;
+  author: { login: string };
+  createdAt: string;
+  closedAt: string | null;
+};
+
+export type IssueListItem = {
+  number: number;
+  title: string;
+  state: string;
+  url: string;
+  labels: Array<{ name: string }>;
+  createdAt: string;
+};
+
+export type RawIssueComment = {
+  id: number;
+  user: { login: string };
+  body: string;
+  created_at: string;
+  html_url: string;
+};
+
+export const listIssues = Effect.fn("issue.listIssues")(function* (opts: {
+  state: string;
+  labels: string | null;
+  limit: number;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = [
+    "issue",
+    "list",
+    "--state",
+    opts.state,
+    "--limit",
+    String(opts.limit),
+    "--json",
+    "number,title,state,url,labels,createdAt",
+  ];
+
+  if (opts.labels !== null) {
+    args.push("--label", opts.labels);
+  }
+
+  return yield* gh.runGhJson<IssueListItem[]>(args);
+});
+
+export const viewIssue = Effect.fn("issue.viewIssue")(function* (issueNumber: number) {
+  const gh = yield* GitHubService;
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(issueNumber),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});
+
+export const closeIssue = Effect.fn("issue.closeIssue")(function* (opts: {
+  issue: number;
+  comment: string | null;
+  reason: string;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["issue", "close", String(opts.issue), "--reason", opts.reason];
+
+  if (opts.comment !== null) {
+    args.push("--comment", opts.comment);
+  }
+
+  yield* gh.runGh(args);
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(opts.issue),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});
+
+export const reopenIssue = Effect.fn("issue.reopenIssue")(function* (opts: {
+  issue: number;
+  comment: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["issue", "reopen", String(opts.issue)];
+
+  if (opts.comment !== null) {
+    args.push("--comment", opts.comment);
+  }
+
+  yield* gh.runGh(args);
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(opts.issue),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});
+
+export const commentOnIssue = Effect.fn("issue.commentOnIssue")(function* (opts: {
+  issue: number;
+  body: string;
+}) {
+  const gh = yield* GitHubService;
+  const repoInfo = yield* gh.getRepoInfo();
+
+  const trimmedBody = opts.body.trim();
+  if (trimmedBody.length === 0) {
+    return yield* Effect.fail(
+      new GitHubCommandError({
+        command: "gh-tool issue comment",
+        exitCode: 0,
+        stderr: "Comment body cannot be empty",
+        message: "Comment body cannot be empty",
+      }),
+    );
+  }
+
+  const result = yield* gh.runGh([
+    "api",
+    "-X",
+    "POST",
+    `repos/${repoInfo.owner}/${repoInfo.name}/issues/${opts.issue}/comments`,
+    "-f",
+    `body=${trimmedBody}`,
+  ]);
+
+  const rawComment = yield* Effect.try({
+    try: () => JSON.parse(result.stdout) as RawIssueComment,
+    catch: (error) =>
+      new GitHubCommandError({
+        command: "gh-tool issue comment",
+        exitCode: 0,
+        stderr: `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
+        message: `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+  }).pipe(Effect.mapError((error) => error as GitHubCommandError));
+
+  return {
+    id: rawComment.id,
+    author: rawComment.user.login,
+    body: rawComment.body,
+    createdAt: rawComment.created_at,
+    url: rawComment.html_url,
+  };
+});
+
+export const editIssue = Effect.fn("issue.editIssue")(function* (opts: {
+  issue: number;
+  title: string | null;
+  body: string | null;
+  addLabels: string | null;
+  removeLabels: string | null;
+  addAssignee: string | null;
+  removeAssignee: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["issue", "edit", String(opts.issue)];
+
+  if (opts.title !== null) {
+    args.push("--title", opts.title);
+  }
+  if (opts.body !== null) {
+    args.push("--body", opts.body);
+  }
+  if (opts.addLabels !== null) {
+    args.push("--add-label", opts.addLabels);
+  }
+  if (opts.removeLabels !== null) {
+    args.push("--remove-label", opts.removeLabels);
+  }
+  if (opts.addAssignee !== null) {
+    args.push("--add-assignee", opts.addAssignee);
+  }
+  if (opts.removeAssignee !== null) {
+    args.push("--remove-assignee", opts.removeAssignee);
+  }
+
+  yield* gh.runGh(args);
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(opts.issue),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});

package/src/gh-tool/issue/index.ts

@@ -0,0 +1,9 @@
+export {
+  issueCloseCommand,
+  issueCommentCommand,
+  issueEditCommand,
+  issueListCommand,
+  issueReopenCommand,
+  issueViewCommand,
+} from "./commands";
+export { issueTriageSummaryCommand } from "./triage";