@mrc2204/openclaw-jira-tools 1.0.1

package/README.en.md

@@ -0,0 +1,127 @@
+# openclaw-jira-tools
+
+Native OpenClaw plugin that registers Jira tools for agents, helping them use Jira consistently, avoid forgetting configuration, and prefer tool-native workflows instead of shelling out to host-level `jira-cli`.
+
+## Goals
+- Standardize Jira tools for OpenClaw agents
+- Avoid dependency on `brew install jira-cli` on the host machine
+- Read Jira configuration from plugin config (`plugins.entries.jira-tools.config`)
+- Support per-agent / per-user defaults to reduce config drift
+- Sanitize fields against Jira `createmeta` / create screen constraints
+- Support Vietnamese-first operational Jira workflows
+
+## Available tools
+
+### Create / defaults
+- `jira_create_task`
+- `jira_create_epic`
+- `jira_create_subtask`
+- `jira_set_defaults`
+- `jira_inspect_project`
+
+### Issue management
+- `jira_issue_list`
+- `jira_issue_view`
+- `jira_open`
+- `jira_issue_edit`
+- `jira_issue_assign`
+- `jira_issue_comment_add`
+- `jira_issue_clone`
+- `jira_issue_delete`
+- `jira_issue_watch`
+- `jira_issue_move`
+- `jira_issue_worklog_add`
+- `jira_issue_link`
+- `jira_issue_unlink`
+
+### Epic / project / board / sprint / release
+- `jira_epic_list`
+- `jira_epic_view`
+- `jira_epic_add`
+- `jira_epic_remove`
+- `jira_project_list`
+- `jira_project_view`
+- `jira_board_list`
+- `jira_sprint_list`
+- `jira_sprint_add`
+- `jira_sprint_close`
+- `jira_release_list`
+- `jira_me`
+- `jira_serverinfo`
+
+## Repository structure
+```text
+openclaw-jira-tools/
+├── openclaw.plugin.json
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts
+│   ├── lib/
+│   ├── shared/
+│   └── tools/
+├── skill/
+│   └── jira/
+│       ├── SKILL.md
+│       └── _meta.json
+└── dist/
+```
+
+## Bundled skill
+This repository also ships a Jira skill to guide agents on how to use the toolset correctly:
+- `skill/jira/SKILL.md`
+- `skill/jira/_meta.json`
+
+The bundled skill documents:
+- issue classification rules
+- Vietnamese issue/comment templates
+- user intent → Jira tool mapping
+- rules for preferring `jira-tools` over host `jira-cli`
+- defaults strategy so agents do not forget configuration
+
+## Correct install from npm
+
+> npm package: https://www.npmjs.com/package/@mrc2204/openclaw-jira-tools
+
+```bash
+openclaw plugins install @mrc2204/openclaw-jira-tools
+```
+
+If you need a local/development workflow, use path-based install separately instead of locking a specific version here.
+
+## Local install for development
+```bash
+cd ~/Work/projects/jira-tools
+npm install
+npm run build
+openclaw plugins install -l ~/Work/projects/jira-tools
+```
+
+## Example config
+```json5
+{
+  plugins: {
+    entries: {
+      "jira-tools": {
+        enabled: true,
+        config: {
+          server: "https://your-domain.atlassian.net",
+          email: "you@example.com",
+          token: "<jira-token>",
+          defaultProject: "TAA",
+          language: "vi",
+          requireClickableLinks: true
+        }
+      }
+    }
+  }
+}
+```
+
+## Notes
+- If an agent allowlist includes `jira-tools`, OpenClaw enables all tools registered by this plugin.
+- This is a plugin-native Jira surface; it does not automatically import every command from a host-installed `jira-cli` binary.
+- Some Epic-related flows may still depend on Jira project screen configuration (for example Epic Name / Epic Link fields).
+
+## License
+MIT

package/README.md

@@ -0,0 +1,129 @@
+# openclaw-jira-tools
+
+> English README: [README.en.md](./README.en.md)
+
+Plugin OpenClaw chuẩn để đăng ký native Jira tools cho agent, giúp agent dùng Jira nhất quán, không quên config và ưu tiên tool-native thay vì shell-out `jira-cli` trên host.
+
+## Mục tiêu
+- Chuẩn hóa Jira tools cho agent trong OpenClaw
+- Không phụ thuộc `brew install jira-cli` trên máy host
+- Đọc config Jira từ plugin config (`plugins.entries.jira-tools.config`)
+- Hỗ trợ defaults theo agent/user để giảm quên config
+- Sanitize field theo Jira `createmeta` / create screen
+- Ưu tiên nội dung tiếng Việt trong flow vận hành Jira
+
+## Bộ tools hiện có
+
+### Tạo issue / defaults
+- `jira_create_task`
+- `jira_create_epic`
+- `jira_create_subtask`
+- `jira_set_defaults`
+- `jira_inspect_project`
+
+### Issue management
+- `jira_issue_list`
+- `jira_issue_view`
+- `jira_open`
+- `jira_issue_edit`
+- `jira_issue_assign`
+- `jira_issue_comment_add`
+- `jira_issue_clone`
+- `jira_issue_delete`
+- `jira_issue_watch`
+- `jira_issue_move`
+- `jira_issue_worklog_add`
+- `jira_issue_link`
+- `jira_issue_unlink`
+
+### Epic / project / board / sprint / release
+- `jira_epic_list`
+- `jira_epic_view`
+- `jira_epic_add`
+- `jira_epic_remove`
+- `jira_project_list`
+- `jira_project_view`
+- `jira_board_list`
+- `jira_sprint_list`
+- `jira_sprint_add`
+- `jira_sprint_close`
+- `jira_release_list`
+- `jira_me`
+- `jira_serverinfo`
+
+## Cấu trúc repo
+```text
+openclaw-jira-tools/
+├── openclaw.plugin.json
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts
+│   ├── lib/
+│   ├── shared/
+│   └── tools/
+├── skill/
+│   └── jira/
+│       ├── SKILL.md
+│       └── _meta.json
+└── dist/
+```
+
+## Skill đi kèm
+Repo này mang kèm skill Jira để hướng dẫn agent dùng bộ tools đúng flow:
+- `skill/jira/SKILL.md`
+- `skill/jira/_meta.json`
+
+Skill này mô tả:
+- chuẩn phân loại issue
+- template tiếng Việt
+- mapping ý định user → tool Jira tương ứng
+- rule dùng `jira-tools` thay cho shell-out `jira-cli`
+- rule defaults để agent không quên config
+
+## Cài đặt đúng từ npm
+
+> Package npm: https://www.npmjs.com/package/@mrc2204/openclaw-jira-tools
+
+```bash
+openclaw plugins install @mrc2204/openclaw-jira-tools
+```
+
+Nếu cần môi trường development/local thì dùng path install riêng, không dùng flow này để khóa version.
+
+## Cài local cho phát triển
+```bash
+cd ~/Work/projects/jira-tools
+npm install
+npm run build
+openclaw plugins install -l ~/Work/projects/jira-tools
+```
+
+## Config mẫu
+```json5
+{
+  plugins: {
+    entries: {
+      "jira-tools": {
+        enabled: true,
+        config: {
+          server: "https://your-domain.atlassian.net",
+          email: "you@example.com",
+          token: "<jira-token>",
+          defaultProject: "TAA",
+          language: "vi",
+          requireClickableLinks: true
+        }
+      }
+    }
+  }
+}
+```
+
+## Ghi chú
+- Nếu allowlist của agent chứa `jira-tools`, OpenClaw sẽ bật toàn bộ tools của plugin này.
+- Đây là plugin-native surface; không tự động import toàn bộ command tree của binary `jira-cli` host.
+- Một số flow Epic có thể vẫn phụ thuộc Jira screen config của project (ví dụ Epic Name / Epic Link field).
+
+## License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const plugin: {
+    id: string;
+    name: string;
+    version: string;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,21 @@
+import { registerCreateTools } from "./tools/create-tools.js";
+import { registerDefaultsTools } from "./tools/defaults-tools.js";
+import { registerInspectTool } from "./tools/inspect-tool.js";
+import { registerManagementTools } from "./tools/management-tools.js";
+const plugin = {
+    id: "jira-tools",
+    name: "Jira Tools",
+    version: "0.1.0",
+    register(api) {
+        const rawConfig = (api.pluginConfig || api?.config?.plugins?.entries?.["jira-tools"]?.config || {});
+        if (!rawConfig.server || !rawConfig.email || !rawConfig.token) {
+            throw new Error("jira-tools requires plugins.entries['jira-tools'].config.server/email/token");
+        }
+        registerCreateTools(api, rawConfig);
+        registerDefaultsTools(api);
+        registerInspectTool(api, rawConfig);
+        registerManagementTools(api, rawConfig);
+        console.log("[jira-tools] Registered tools: jira_create_task, jira_create_epic, jira_create_subtask, jira_set_defaults, jira_inspect_project, jira_me, jira_serverinfo, jira_project_list, jira_project_view, jira_issue_list, jira_issue_view, jira_open, jira_issue_edit, jira_issue_assign, jira_issue_comment_add, jira_issue_clone, jira_issue_delete, jira_issue_watch, jira_issue_move, jira_issue_worklog_add, jira_issue_link, jira_issue_unlink, jira_epic_list, jira_epic_view, jira_epic_add, jira_epic_remove, jira_board_list, jira_sprint_list, jira_sprint_add, jira_sprint_close, jira_release_list");
+    },
+};
+export default plugin;

package/dist/lib/defaults-store.d.ts

@@ -0,0 +1,8 @@
+import type { JiraDefaultsRecord } from "../shared/types.js";
+export declare class JiraDefaultsStore {
+    private baseDir;
+    constructor(baseDir?: string);
+    private filePath;
+    get(agentId: string, userId: string): JiraDefaultsRecord;
+    set(agentId: string, userId: string, patch: JiraDefaultsRecord): JiraDefaultsRecord;
+}

package/dist/lib/defaults-store.js

@@ -0,0 +1,27 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+function safeKey(input) {
+    return input.replace(/[^a-zA-Z0-9._-]+/g, "_");
+}
+export class JiraDefaultsStore {
+    baseDir;
+    constructor(baseDir) {
+        const stateDir = process.env.OPENCLAW_STATE_DIR || `${process.env.HOME}/.openclaw`;
+        this.baseDir = baseDir || join(stateDir, "plugin-data", "jira-tools", "defaults");
+        mkdirSync(this.baseDir, { recursive: true });
+    }
+    filePath(agentId, userId) {
+        return join(this.baseDir, `${safeKey(agentId)}__${safeKey(userId)}.json`);
+    }
+    get(agentId, userId) {
+        const fp = this.filePath(agentId, userId);
+        if (!existsSync(fp))
+            return {};
+        return JSON.parse(readFileSync(fp, "utf8"));
+    }
+    set(agentId, userId, patch) {
+        const next = { ...this.get(agentId, userId), ...patch };
+        writeFileSync(this.filePath(agentId, userId), JSON.stringify(next, null, 2), "utf8");
+        return next;
+    }
+}

package/dist/lib/jira-client.d.ts

@@ -0,0 +1,36 @@
+import type { JiraCreateInput, JiraDefaultsRecord, JiraToolsConfig } from "../shared/types.js";
+export interface JiraResolvedConfig {
+    server: string;
+    email: string;
+    token: string;
+    defaultProject: string;
+    language: string;
+    requireClickableLinks: boolean;
+    issueTypeMap: {
+        task: string;
+        epic: string;
+        subtask: string;
+    };
+    fieldMappings: {
+        epicName: string;
+        epicLink: string;
+        parentLink: string;
+    };
+}
+export declare class JiraClient {
+    private readonly config;
+    constructor(config: JiraResolvedConfig);
+    private headers;
+    request(path: string, init?: RequestInit): Promise<any>;
+    issueUrl(issueKey: string): string;
+    getProject(projectKey: string): Promise<any>;
+    getCreateMeta(projectKey: string, issueTypeName: string): Promise<any>;
+    searchUsers(query: string): Promise<any>;
+    getIssue(issueKey: string): Promise<any>;
+    resolveAssigneeAccountId(email?: string, displayName?: string): Promise<string | undefined>;
+    buildDescription(kind: string, summary: string, objective: string, technicalDetails: string, dod: string, links?: string[], parentKey?: string): any;
+    sanitizeFields(fields: Record<string, any>, createmeta: any): Record<string, any>;
+    createIssue(fields: Record<string, any>): Promise<any>;
+}
+export declare function resolveConfig(raw: JiraToolsConfig): JiraResolvedConfig;
+export declare function mergeDefaults(input: JiraCreateInput, defaults: JiraDefaultsRecord): JiraCreateInput;

package/dist/lib/jira-client.js

@@ -0,0 +1,112 @@
+export class JiraClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    headers() {
+        return {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "Authorization": `Basic ${Buffer.from(`${this.config.email}:${this.config.token}`).toString("base64")}`,
+        };
+    }
+    async request(path, init) {
+        const res = await fetch(`${this.config.server}${path}`, {
+            ...init,
+            headers: { ...this.headers(), ...(init?.headers || {}) },
+        });
+        const text = await res.text();
+        const payload = text ? JSON.parse(text) : {};
+        if (!res.ok)
+            throw new Error(`${res.status}: ${JSON.stringify(payload)}`);
+        return payload;
+    }
+    issueUrl(issueKey) {
+        return `${this.config.server}/browse/${issueKey}`;
+    }
+    async getProject(projectKey) {
+        return this.request(`/rest/api/3/project/${projectKey}`);
+    }
+    async getCreateMeta(projectKey, issueTypeName) {
+        const q = new URLSearchParams({
+            projectKeys: projectKey,
+            issuetypeNames: issueTypeName,
+            expand: "projects.issuetypes.fields",
+        });
+        return this.request(`/rest/api/3/issue/createmeta?${q.toString()}`);
+    }
+    async searchUsers(query) {
+        const q = new URLSearchParams({ query, maxResults: "20" });
+        return this.request(`/rest/api/3/user/search?${q.toString()}`);
+    }
+    async getIssue(issueKey) {
+        return this.request(`/rest/api/3/issue/${issueKey}`);
+    }
+    async resolveAssigneeAccountId(email, displayName) {
+        const query = email || displayName;
+        if (!query)
+            return undefined;
+        const users = await this.searchUsers(query);
+        if (!Array.isArray(users) || users.length === 0)
+            throw new Error(`Không tìm thấy assignee: ${query}`);
+        const exact = users.find((u) => (email && u.emailAddress === email) || (displayName && u.displayName === displayName));
+        return (exact || users[0]).accountId;
+    }
+    buildDescription(kind, summary, objective, technicalDetails, dod, links, parentKey) {
+        const lines = [
+            `## Loại issue`, `- ${kind}`,
+            ``, `## Mục tiêu`, objective,
+            ``, `## Chi tiết kỹ thuật`, technicalDetails,
+            ``, `## Tiêu chuẩn hoàn thành (DoD)`, dod,
+        ];
+        if (parentKey)
+            lines.push("", "## Issue cha", `- ${parentKey}`, `- Link: ${this.issueUrl(parentKey)}`);
+        if (links && links.length)
+            lines.push("", "## Links liên quan", ...links.map((x) => `- ${x}`));
+        lines.push("", "## Ghi chú", "- Nội dung và comment Jira dùng tiếng Việt.");
+        const content = lines.map((line) => line ? ({ type: "paragraph", content: [{ type: "text", text: line }] }) : ({ type: "paragraph", content: [] }));
+        return { type: "doc", version: 1, content };
+    }
+    sanitizeFields(fields, createmeta) {
+        const allowed = new Set();
+        const projects = createmeta?.projects || [];
+        const issueTypes = projects[0]?.issuetypes || [];
+        const metaFields = issueTypes[0]?.fields || {};
+        for (const k of Object.keys(metaFields))
+            allowed.add(k);
+        const keep = new Set(["project", "summary", "description", "issuetype", "labels", "assignee", "parent"]);
+        return Object.fromEntries(Object.entries(fields).filter(([k]) => keep.has(k) || allowed.has(k)));
+    }
+    async createIssue(fields) {
+        return this.request(`/rest/api/3/issue`, { method: "POST", body: JSON.stringify({ fields }) });
+    }
+}
+export function resolveConfig(raw) {
+    return {
+        server: raw.server.replace(/\/$/, ""),
+        email: raw.email,
+        token: raw.token,
+        defaultProject: raw.defaultProject || "TAA",
+        language: raw.language || "vi",
+        requireClickableLinks: raw.requireClickableLinks !== false,
+        issueTypeMap: {
+            task: raw.issueTypeMap?.task || "Task",
+            epic: raw.issueTypeMap?.epic || "Epic",
+            subtask: raw.issueTypeMap?.subtask || "Subtask",
+        },
+        fieldMappings: {
+            epicName: raw.fieldMappings?.epicName || "customfield_10011",
+            epicLink: raw.fieldMappings?.epicLink || "customfield_10014",
+            parentLink: raw.fieldMappings?.parentLink || "customfield_10018",
+        },
+    };
+}
+export function mergeDefaults(input, defaults) {
+    return {
+        ...input,
+        project: input.project || defaults.defaultProject,
+        assigneeEmail: input.assigneeEmail || defaults.assigneeEmail,
+        assigneeName: input.assigneeName || defaults.assigneeName,
+        labels: input.labels?.length ? input.labels : defaults.labels,
+    };
+}

package/dist/lib/runtime.d.ts

@@ -0,0 +1,17 @@
+export declare function getSessionKey(ctx: any): string;
+export declare function parseSessionIdentity(sessionKey: string): {
+    agentId: string;
+    userId: string;
+};
+export declare function createToolResult(text: string, isError?: boolean): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: {
+        toolResult: {
+            text: string;
+        };
+    };
+    isError: boolean;
+};

package/dist/lib/runtime.js

@@ -0,0 +1,21 @@
+export function getSessionKey(ctx) {
+    return String(ctx?.sessionKey ||
+        ctx?.session?.key ||
+        ctx?.session?.sessionKey ||
+        ctx?.meta?.sessionKey ||
+        "main");
+}
+export function parseSessionIdentity(sessionKey) {
+    const parts = sessionKey.split(":");
+    if (parts.length >= 5 && parts[0] === "agent") {
+        return { agentId: parts[1] || "main", userId: parts[4] || "main" };
+    }
+    return { agentId: "main", userId: sessionKey || "main" };
+}
+export function createToolResult(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        details: { toolResult: { text } },
+        isError,
+    };
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,41 @@
+export interface JiraToolsConfig {
+    server: string;
+    email: string;
+    token: string;
+    defaultProject?: string;
+    language?: string;
+    requireClickableLinks?: boolean;
+    issueTypeMap?: {
+        task?: string;
+        epic?: string;
+        subtask?: string;
+    };
+    fieldMappings?: {
+        epicName?: string;
+        epicLink?: string;
+        parentLink?: string;
+    };
+}
+export interface JiraDefaultsRecord {
+    defaultProject?: string;
+    assigneeEmail?: string;
+    assigneeName?: string;
+    labels?: string[];
+    epicKey?: string;
+    parentLink?: string;
+    templateTask?: string;
+    templateEpic?: string;
+    templateSubtask?: string;
+}
+export interface JiraCreateInput {
+    project?: string;
+    summary: string;
+    body?: string;
+    objective?: string;
+    technicalDetails?: string;
+    dod?: string;
+    labels?: string[];
+    links?: string[];
+    assigneeEmail?: string;
+    assigneeName?: string;
+}

package/dist/shared/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/create-tools.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { JiraToolsConfig } from "../shared/types.js";
+export declare function registerCreateTools(api: OpenClawPluginApi, rawConfig: JiraToolsConfig): void;