@commandable/integration-data 0.0.6 → 0.1.0

package/integrations/jira/handlers/get_project.js

@@ -0,0 +1,28 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.expandIssueTypes !== false)
+    params.set('expand', 'issueTypes')
+
+  const path = `/rest/api/3/project/${encodeURIComponent(input.projectIdOrKey)}${params.toString() ? `?${params.toString()}` : ''}`
+  const res = await integration.fetch(path)
+  const data = await res.json()
+
+  const issueTypes = Array.isArray(data.issueTypes) ? data.issueTypes : []
+
+  return {
+    id: data.id ?? null,
+    key: data.key ?? null,
+    name: data.name ?? null,
+    projectTypeKey: data.projectTypeKey ?? null,
+    simplified: data.simplified ?? null,
+    style: data.style ?? null,
+    isPrivate: data.isPrivate ?? null,
+    issueTypes: issueTypes.map(t => ({
+      id: t.id ?? null,
+      name: t.name ?? null,
+      description: t.description ?? null,
+      subtask: t.subtask ?? null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/get_sprint.js

@@ -0,0 +1,5 @@
+async (input) => {
+  const res = await integration.fetch(`/rest/agile/1.0/sprint/${encodeURIComponent(String(input.sprintId))}`)
+  return await res.json()
+}
+

package/integrations/jira/handlers/get_sprint_issues.js

@@ -0,0 +1,13 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input.jql)
+    params.set('jql', input.jql)
+  if (Array.isArray(input.fields) && input.fields.length)
+    params.set('fields', input.fields.join(','))
+  params.set('startAt', String(input.startAt ?? 0))
+  params.set('maxResults', String(input.maxResults ?? 50))
+
+  const res = await integration.fetch(`/rest/agile/1.0/sprint/${encodeURIComponent(String(input.sprintId))}/issue?${params.toString()}`)
+  return await res.json()
+}
+

package/integrations/jira/handlers/get_transitions.js

@@ -0,0 +1,23 @@
+async (input) => {
+  const path = `/rest/api/3/issue/${encodeURIComponent(input.issueIdOrKey)}/transitions`
+  const res = await integration.fetch(path)
+  const data = await res.json()
+  const transitions = Array.isArray(data.transitions) ? data.transitions : []
+
+  return {
+    transitions: transitions.map(t => ({
+      id: t.id ?? null,
+      name: t.name ?? null,
+      to: t.to
+        ? {
+            id: t.to.id ?? null,
+            name: t.to.name ?? null,
+            statusCategory: t.to.statusCategory
+              ? { key: t.to.statusCategory.key ?? null, name: t.to.statusCategory.name ?? null }
+              : null,
+          }
+        : null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/list_boards.js

@@ -0,0 +1,34 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input?.projectKeyOrId)
+    params.set('projectKeyOrId', input.projectKeyOrId)
+  if (input?.type)
+    params.set('type', input.type)
+  params.set('startAt', String(input?.startAt ?? 0))
+  params.set('maxResults', String(input?.maxResults ?? 50))
+
+  const res = await integration.fetch(`/rest/agile/1.0/board?${params.toString()}`)
+  const data = await res.json()
+  const values = Array.isArray(data.values) ? data.values : []
+
+  return {
+    startAt: data.startAt ?? (input?.startAt ?? 0),
+    maxResults: data.maxResults ?? (input?.maxResults ?? 50),
+    total: data.total ?? values.length,
+    isLast: Boolean(data.isLast),
+    boards: values.map(b => ({
+      id: b.id ?? null,
+      name: b.name ?? null,
+      type: b.type ?? null,
+      location: b.location
+        ? {
+            projectId: b.location.projectId ?? null,
+            projectKey: b.location.projectKey ?? null,
+            projectName: b.location.projectName ?? null,
+          }
+        : null,
+      self: b.self ?? null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/list_projects.js

@@ -0,0 +1,29 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (input?.query)
+    params.set('query', input.query)
+  params.set('startAt', String(input?.startAt ?? 0))
+  params.set('maxResults', String(input?.maxResults ?? 50))
+
+  const path = `/rest/api/3/project/search?${params.toString()}`
+  const res = await integration.fetch(path)
+  const data = await res.json()
+  const values = Array.isArray(data.values) ? data.values : []
+
+  return {
+    startAt: data.startAt ?? (input?.startAt ?? 0),
+    maxResults: data.maxResults ?? (input?.maxResults ?? 50),
+    total: data.total ?? values.length,
+    isLast: Boolean(data.isLast),
+    projects: values.map(p => ({
+      id: p.id ?? null,
+      key: p.key ?? null,
+      name: p.name ?? null,
+      projectTypeKey: p.projectTypeKey ?? null,
+      simplified: p.simplified ?? null,
+      style: p.style ?? null,
+      isPrivate: p.isPrivate ?? null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/list_sprints.js

@@ -0,0 +1,29 @@
+async (input) => {
+  const params = new URLSearchParams()
+  if (Array.isArray(input.state) && input.state.length)
+    params.set('state', input.state.join(','))
+  params.set('startAt', String(input.startAt ?? 0))
+  params.set('maxResults', String(input.maxResults ?? 50))
+
+  const res = await integration.fetch(`/rest/agile/1.0/board/${encodeURIComponent(String(input.boardId))}/sprint?${params.toString()}`)
+  const data = await res.json()
+  const values = Array.isArray(data.values) ? data.values : []
+
+  return {
+    startAt: data.startAt ?? (input.startAt ?? 0),
+    maxResults: data.maxResults ?? (input.maxResults ?? 50),
+    total: data.total ?? values.length,
+    isLast: Boolean(data.isLast),
+    sprints: values.map(s => ({
+      id: s.id ?? null,
+      name: s.name ?? null,
+      state: s.state ?? null,
+      goal: s.goal ?? null,
+      startDate: s.startDate ?? null,
+      endDate: s.endDate ?? null,
+      completeDate: s.completeDate ?? null,
+      self: s.self ?? null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/move_issues_to_sprint.js

@@ -0,0 +1,11 @@
+async (input) => {
+  const res = await integration.fetch(`/rest/agile/1.0/sprint/${encodeURIComponent(String(input.sprintId))}/issue`, {
+    method: 'POST',
+    body: { issues: input.issueKeys },
+  })
+
+  if (res.status === 204)
+    return { success: true }
+  return await res.json()
+}
+

package/integrations/jira/handlers/search_issues.js

@@ -0,0 +1,43 @@
+async (input) => {
+  const body = {
+    jql: input.jql,
+    maxResults: input.maxResults ?? 50,
+  }
+
+  if (Array.isArray(input.fields) && input.fields.length)
+    body.fields = input.fields
+  if (input.nextPageToken)
+    body.nextPageToken = input.nextPageToken
+
+  const res = await integration.fetch('/rest/api/3/search/jql', {
+    method: 'POST',
+    body,
+  })
+
+  const data = await res.json()
+  const issues = Array.isArray(data.issues) ? data.issues : []
+
+  return {
+    isLast: Boolean(data.isLast),
+    nextPageToken: data.nextPageToken ?? null,
+    issues: issues.map((i) => ({
+      id: i.id,
+      key: i.key,
+      summary: i.fields?.summary ?? null,
+      status: i.fields?.status?.name ?? null,
+      assignee: i.fields?.assignee
+        ? {
+            accountId: i.fields.assignee.accountId ?? null,
+            displayName: i.fields.assignee.displayName ?? null,
+          }
+        : null,
+      priority: i.fields?.priority?.name ?? null,
+      issueType: i.fields?.issuetype?.name ?? null,
+      project: i.fields?.project
+        ? { key: i.fields.project.key ?? null, name: i.fields.project.name ?? null }
+        : null,
+      updated: i.fields?.updated ?? null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/search_users.js

@@ -0,0 +1,21 @@
+async (input) => {
+  const params = new URLSearchParams()
+  params.set('query', input.query)
+  params.set('maxResults', String(input.maxResults ?? 50))
+
+  const res = await integration.fetch(`/rest/api/3/user/search?${params.toString()}`)
+  const data = await res.json()
+  const users = Array.isArray(data) ? data : []
+
+  return {
+    users: users.map(u => ({
+      accountId: u.accountId ?? null,
+      displayName: u.displayName ?? null,
+      active: u.active ?? null,
+      accountType: u.accountType ?? null,
+      emailAddress: u.emailAddress ?? null,
+      timeZone: u.timeZone ?? null,
+    })),
+  }
+}
+

package/integrations/jira/handlers/transition_issue.js

@@ -0,0 +1,44 @@
+async (input) => {
+  const resolveTransitionId = async (issueIdOrKey, transitionId, transitionName) => {
+    if (transitionId)
+      return String(transitionId)
+    const name = String(transitionName || '').trim().toLowerCase()
+    if (!name)
+      return null
+
+    const res = await integration.fetch(`/rest/api/3/issue/${encodeURIComponent(issueIdOrKey)}/transitions`)
+    const data = await res.json()
+    const transitions = Array.isArray(data.transitions) ? data.transitions : []
+    const match = transitions.find(t => String(t?.name || '').trim().toLowerCase() === name)
+    return match?.id ? String(match.id) : null
+  }
+
+  const id = await resolveTransitionId(input.issueIdOrKey, input.transitionId, input.transitionName)
+  if (!id)
+    throw new Error(`Could not resolve transition. Provide a valid transitionId or transitionName (call get_transitions to see available transitions).`)
+
+  const body = {
+    transition: { id },
+  }
+
+  if (input.fields && typeof input.fields === 'object')
+    body.fields = input.fields
+  if (input.update && typeof input.update === 'object')
+    body.update = input.update
+
+  if (input.commentText) {
+    body.update = body.update || {}
+    body.update.comment = body.update.comment || []
+    body.update.comment.push({ add: { body: utils.adf?.fromMarkdown(input.commentText) } })
+  }
+
+  const res = await integration.fetch(`/rest/api/3/issue/${encodeURIComponent(input.issueIdOrKey)}/transitions`, {
+    method: 'POST',
+    body,
+  })
+
+  if (res.status === 204)
+    return { success: true }
+  return await res.json()
+}
+

package/integrations/jira/handlers/update_issue.js

@@ -0,0 +1,40 @@
+async (input) => {
+  const fields = { ...(input.fields || {}) }
+  const update = input.update ? { ...(input.update || {}) } : undefined
+
+  if (typeof input.summary === 'string')
+    fields.summary = input.summary
+
+  if (typeof input.descriptionText === 'string')
+    fields.description = utils.adf?.fromMarkdown(input.descriptionText)
+
+  if (Array.isArray(input.labels))
+    fields.labels = input.labels
+
+  if (input.priorityId)
+    fields.priority = { id: input.priorityId }
+  else if (input.priorityName)
+    fields.priority = { name: input.priorityName }
+
+  if (input.assigneeAccountId !== undefined) {
+    fields.assignee = input.assigneeAccountId === null
+      ? null
+      : { accountId: input.assigneeAccountId }
+  }
+
+  const body = {}
+  if (Object.keys(fields).length)
+    body.fields = fields
+  if (update && Object.keys(update).length)
+    body.update = update
+
+  const res = await integration.fetch(`/rest/api/3/issue/${encodeURIComponent(input.issueIdOrKey)}`, {
+    method: 'PUT',
+    body,
+  })
+
+  if (res.status === 204)
+    return { success: true }
+  return await res.json()
+}
+

package/integrations/jira/handlers/update_sprint.js

@@ -0,0 +1,20 @@
+async (input) => {
+  const body = {}
+  if (input.name !== undefined)
+    body.name = input.name
+  if (input.goal !== undefined)
+    body.goal = input.goal
+  if (input.state !== undefined)
+    body.state = input.state
+  if (input.startDate !== undefined)
+    body.startDate = input.startDate
+  if (input.endDate !== undefined)
+    body.endDate = input.endDate
+
+  const res = await integration.fetch(`/rest/agile/1.0/sprint/${encodeURIComponent(String(input.sprintId))}`, {
+    method: 'POST',
+    body,
+  })
+
+  return await res.json()
+}

package/integrations/jira/manifest.json

@@ -0,0 +1,204 @@
+{
+  "name": "jira",
+  "version": "0.1.0",
+  "utils": ["adf"],
+  "toolsets": {
+    "issues": {
+      "label": "Issues",
+      "description": "Search, read, create, and manage Jira issues"
+    },
+    "boards": {
+      "label": "Boards & Sprints",
+      "description": "Work with Jira Software boards, sprints, and backlogs"
+    }
+  },
+  "tools": [
+    {
+      "name": "search_issues",
+      "description": "Search for issues using JQL. Returns a compact list of issues with key fields. Uses the modern /search/jql endpoint with nextPageToken pagination.",
+      "inputSchema": "schemas/search_issues.json",
+      "handler": "handlers/search_issues.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "get_issue",
+      "description": "Get details for a Jira issue by key (e.g. PROJ-123). Converts the issue description from Jira ADF into Markdown for easier reading.",
+      "inputSchema": "schemas/get_issue.json",
+      "handler": "handlers/get_issue.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "get_issue_comments",
+      "description": "List comments on an issue. Converts each comment body from Jira ADF into Markdown.",
+      "inputSchema": "schemas/get_issue_comments.json",
+      "handler": "handlers/get_issue_comments.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "list_projects",
+      "description": "List accessible Jira projects (key, name, type). Use this before creating issues to discover valid project keys.",
+      "inputSchema": "schemas/list_projects.json",
+      "handler": "handlers/list_projects.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "get_project",
+      "description": "Get a project by key or ID. Includes issue types when expandIssueTypes=true, which is useful to choose a valid issue type name before create_issue.",
+      "inputSchema": "schemas/get_project.json",
+      "handler": "handlers/get_project.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "get_transitions",
+      "description": "List available workflow transitions for an issue. Use this to discover valid transition names/IDs before calling transition_issue.",
+      "inputSchema": "schemas/get_transitions.json",
+      "handler": "handlers/get_transitions.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "get_myself",
+      "description": "Get the authenticated Jira user profile for the current credentials.",
+      "inputSchema": "schemas/empty.json",
+      "handler": "handlers/get_myself.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+    {
+      "name": "search_users",
+      "description": "Search for users and return accountIds for assignment. Use this to find assigneeAccountId values for create_issue/update_issue/assign_issue.",
+      "inputSchema": "schemas/search_users.json",
+      "handler": "handlers/search_users.js",
+      "scope": "read",
+      "toolset": "issues"
+    },
+
+    {
+      "name": "create_issue",
+      "description": "Create a new Jira issue. Provide descriptionText as Markdown; the handler converts it to Jira ADF automatically. Use get_project to discover valid issue types.",
+      "inputSchema": "schemas/create_issue.json",
+      "handler": "handlers/create_issue.js",
+      "scope": "write",
+      "toolset": "issues"
+    },
+    {
+      "name": "update_issue",
+      "description": "Update a Jira issue. You can use simple fields like summary/descriptionText/labels/priorityName/assigneeAccountId, or pass advanced Jira 'fields'/'update' objects for complex updates. descriptionText is treated as Markdown and converted to ADF automatically.",
+      "inputSchema": "schemas/update_issue.json",
+      "handler": "handlers/update_issue.js",
+      "scope": "write",
+      "toolset": "issues"
+    },
+    {
+      "name": "transition_issue",
+      "description": "Transition an issue to a new workflow status. Provide transitionId or transitionName. If transitionName is provided, the handler resolves it by fetching transitions first. Optionally add a comment during the transition (commentText is treated as Markdown and converted to ADF).",
+      "inputSchema": "schemas/transition_issue.json",
+      "handler": "handlers/transition_issue.js",
+      "scope": "write",
+      "toolset": "issues"
+    },
+    {
+      "name": "add_comment",
+      "description": "Add a comment to an issue. Provide bodyText as Markdown; the handler converts it to Jira ADF automatically.",
+      "inputSchema": "schemas/add_comment.json",
+      "handler": "handlers/add_comment.js",
+      "scope": "write",
+      "toolset": "issues"
+    },
+    {
+      "name": "assign_issue",
+      "description": "Assign an issue to a user (by accountId) or unassign it (accountId=null). Use search_users to find accountIds.",
+      "inputSchema": "schemas/assign_issue.json",
+      "handler": "handlers/assign_issue.js",
+      "scope": "write",
+      "toolset": "issues"
+    },
+    {
+      "name": "delete_issue",
+      "description": "Delete an issue. This is irreversible. Use with care.",
+      "inputSchema": "schemas/delete_issue.json",
+      "handler": "handlers/delete_issue.js",
+      "scope": "write",
+      "toolset": "issues"
+    },
+
+    {
+      "name": "list_boards",
+      "description": "List Jira Software boards. Filter by projectKeyOrId and board type (scrum/kanban).",
+      "inputSchema": "schemas/list_boards.json",
+      "handler": "handlers/list_boards.js",
+      "scope": "read",
+      "toolset": "boards"
+    },
+    {
+      "name": "get_board",
+      "description": "Get details for a Jira Software board by boardId.",
+      "inputSchema": "schemas/get_board.json",
+      "handler": "handlers/get_board.js",
+      "scope": "read",
+      "toolset": "boards"
+    },
+    {
+      "name": "list_sprints",
+      "description": "List sprints for a board. Optionally filter by sprint state (future/active/closed).",
+      "inputSchema": "schemas/list_sprints.json",
+      "handler": "handlers/list_sprints.js",
+      "scope": "read",
+      "toolset": "boards"
+    },
+    {
+      "name": "get_sprint",
+      "description": "Get sprint details by sprintId (name, state, start/end dates, goal).",
+      "inputSchema": "schemas/get_sprint.json",
+      "handler": "handlers/get_sprint.js",
+      "scope": "read",
+      "toolset": "boards"
+    },
+    {
+      "name": "get_sprint_issues",
+      "description": "List issues in a sprint. Useful for sprint status reports and review preparation.",
+      "inputSchema": "schemas/get_sprint_issues.json",
+      "handler": "handlers/get_sprint_issues.js",
+      "scope": "read",
+      "toolset": "boards"
+    },
+    {
+      "name": "get_backlog_issues",
+      "description": "List issues in the backlog for a board.",
+      "inputSchema": "schemas/get_backlog_issues.json",
+      "handler": "handlers/get_backlog_issues.js",
+      "scope": "read",
+      "toolset": "boards"
+    },
+    {
+      "name": "move_issues_to_sprint",
+      "description": "Move one or more issues into a sprint (agile API).",
+      "inputSchema": "schemas/move_issues_to_sprint.json",
+      "handler": "handlers/move_issues_to_sprint.js",
+      "scope": "write",
+      "toolset": "boards"
+    },
+    {
+      "name": "create_sprint",
+      "description": "Create a sprint in a board (agile API). Use this for sprint-planning workflows and for integration test setup.",
+      "inputSchema": "schemas/create_sprint.json",
+      "handler": "handlers/create_sprint.js",
+      "scope": "write",
+      "toolset": "boards"
+    },
+    {
+      "name": "update_sprint",
+      "description": "Update a sprint (agile API). Use to rename, set/change goal, start a sprint (state: active, requires startDate + endDate), or close it (state: closed). Partial update — only provided fields are changed.",
+      "inputSchema": "schemas/update_sprint.json",
+      "handler": "handlers/update_sprint.js",
+      "scope": "write",
+      "toolset": "boards"
+    }
+  ]
+}
+

package/integrations/jira/prompt.md

@@ -0,0 +1,80 @@
+# Jira usage guide
+
+## Core workflow patterns
+
+### Discover projects and issue types (before creating issues)
+
+1. Call `list_projects` to find the project key (e.g. `PROJ`).
+2. Call `get_project` with `projectIdOrKey=PROJ` to see available `issueTypes`.
+3. Use the returned issue type name with `create_issue.issueTypeName`.
+
+### Search issues (JQL)
+
+Use `search_issues` with JQL. Common examples:
+
+- My open issues:
+  - `assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC`
+- Recently updated issues in a project:
+  - `project = PROJ ORDER BY updated DESC`
+- Unassigned bugs:
+  - `project = PROJ AND issuetype = Bug AND assignee is EMPTY ORDER BY created DESC`
+- Blocked issues (label-based):
+  - `project = PROJ AND labels = blocked ORDER BY priority DESC, updated DESC`
+
+Pagination:
+- `search_issues` uses `nextPageToken`. If `nextPageToken` is returned and `isLast=false`, pass it back to get the next page.
+
+### Read issue content
+
+- Use `get_issue` to read a compact issue summary.
+- `get_issue` converts Jira's ADF description into `descriptionMarkdown` when possible (fallback: `descriptionText`).
+- Use `get_issue_comments` to read the comment thread (comment bodies are converted to Markdown).
+
+### Transition an issue (change status)
+
+Jira workflows are project-specific, so you must discover valid transitions:
+
+1. Call `get_transitions` to see available transition names/IDs for the issue.
+2. Call `transition_issue` using either `transitionId` (preferred) or `transitionName`.
+
+### Assigning issues
+
+1. Call `search_users` to find the user's `accountId`.
+2. Assign:
+   - `assign_issue { issueIdOrKey, accountId }`
+3. Unassign:
+   - `assign_issue { issueIdOrKey, accountId: null }`
+
+## Notes on Jira rich text (ADF)
+
+Jira Cloud REST API v3 uses **Atlassian Document Format (ADF)** for fields like `description` and comment bodies.
+
+- Read tools convert ADF to Markdown so you can read it directly.
+- Write tools accept **Markdown** in their `*Text` fields and convert it to ADF (`descriptionText`, `bodyText`, `commentText`).
+
+### Round-trip Markdown workflow (recommended)
+
+You can safely do a Markdown round-trip:
+
+1. `get_issue` -> edit `descriptionMarkdown`
+2. `update_issue { descriptionText: <your edited Markdown> }`
+
+Supported Markdown features when writing:
+
+- Headings (`#`, `##`, ...)
+- Bold/italic/strikethrough (`**bold**`, `*italic*`, `~~strike~~`)
+- Inline code and fenced code blocks (```), including optional language fences
+- Lists (ordered/unordered), nested lists
+- Blockquotes (`>`)
+- Horizontal rules (`---`)
+- Tables
+- Links (`[text](url)`)
+
+## Boards & sprints
+
+If you’re using Jira Software:
+
+1. Call `list_boards` (optionally filter by `projectKeyOrId`).
+2. Call `list_sprints` for a board to find active/future sprints.
+3. Use `move_issues_to_sprint` to pull work into a sprint (sprint planning).
+

package/integrations/jira/schemas/add_comment.json

@@ -0,0 +1,16 @@
+{
+  "type": "object",
+  "properties": {
+    "issueIdOrKey": {
+      "type": "string",
+      "description": "Issue key like \"PROJ-123\" or numeric issue ID."
+    },
+    "bodyText": {
+      "type": "string",
+      "description": "Plain-text comment body. Converted to ADF by the handler."
+    }
+  },
+  "required": ["issueIdOrKey", "bodyText"],
+  "additionalProperties": false
+}
+

package/integrations/jira/schemas/assign_issue.json

@@ -0,0 +1,16 @@
+{
+  "type": "object",
+  "properties": {
+    "issueIdOrKey": {
+      "type": "string",
+      "description": "Issue key like \"PROJ-123\" or numeric issue ID."
+    },
+    "accountId": {
+      "type": ["string", "null"],
+      "description": "Account ID to assign the issue to, or null to unassign."
+    }
+  },
+  "required": ["issueIdOrKey", "accountId"],
+  "additionalProperties": false
+}
+