@dreki-gg/pi-jira 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @dreki-gg/pi-jira
+
+## 0.2.0
+
+### Minor Changes
+
+- New extension: Jira tools backed by an authenticated Atlassian CLI (`acli`)
+  session. `jira_view` pulls a ticket's description and comments into context,
+  `jira_search` runs JQL queries, `jira_comments` reads a ticket's thread, and
+  `jira_comment` posts a concise comment back. Every read tool returns a compact
+  digest inline and writes the full, untruncated output to a temp file (so long
+  descriptions and comment threads survive harness truncation — the agent reads
+  the file). A `/jira` command reports auth and config status, and `.pi/jira.json`
+  supports `acliPath`, `defaultProject`, `viewFields`, and `searchLimit`.

package/README.md

@@ -0,0 +1,64 @@
+# @dreki-gg/pi-jira
+
+Jira tools for [pi](https://github.com/earendil-works/pi-coding-agent) that ride on an **authenticated Atlassian CLI (`acli`) session** — pull ticket context into the agent and post concise comments back. No API tokens to manage in pi; auth lives entirely in your `acli` session.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `jira_view` | Fetch a work item (description + comments) for context. Returns a compact digest inline and writes the full ticket to a temp file for `read`. |
+| `jira_search` | Search work items with JQL. Returns a compact list of keys, statuses, and summaries. |
+| `jira_comments` | List the comment thread on a work item. |
+| `jira_comment` | Post a concise comment to a work item. |
+
+There is also a `/jira` command that reports auth + config status.
+
+## Setup
+
+### 1. Install and authenticate the Atlassian CLI
+
+Install [`acli`](https://developer.atlassian.com/cloud/acli/) and log in **once** in your terminal:
+
+```bash
+acli jira auth login
+acli jira auth status   # confirm you have an active session
+```
+
+pi reuses that session — it never sees your credentials.
+
+### 2. Install the extension
+
+```bash
+pi install npm:@dreki-gg/pi-jira
+```
+
+On session start the extension runs `acli jira auth status`; if there is no active session it warns you to run `acli jira auth login`.
+
+## Project config (optional)
+
+Create `.pi/jira.json` in your project root:
+
+```json
+{
+  "acliPath": "acli",
+  "defaultProject": "PROJ",
+  "viewFields": "summary,issuetype,status,priority,assignee,reporter,labels,components,parent,description,comment,created,updated",
+  "searchLimit": 25
+}
+```
+
+| Field | Default | Purpose |
+|-------|---------|---------|
+| `acliPath` | `"acli"` | Path/name of the `acli` binary. Set this if `acli` is not on `PATH`. |
+| `defaultProject` | _(none)_ | Lets you pass a bare number (e.g. `123` → `PROJ-123`). |
+| `viewFields` | curated set | Fields requested by `jira_view` (`acli` `--fields` syntax; `*all` for everything). |
+| `searchLimit` | `25` | Default max results for `jira_search`. |
+
+## How context flows
+
+**Invariant: every read tool returns a compact digest inline and writes the full, untruncated output to a temp file whose path is in the response.** Inline content can be truncated by the harness, so the on-disk copy is the source of truth — `read` the file path instead of re-fetching. Atlassian Document Format is flattened to text in both. Which tools write files, the digest shape, and the filename pattern are owned by `extensions/jira/index.ts` + `format.ts`, not restated here.
+
+## Notes
+
+- Comments are visible to your whole team. The agent is instructed to keep them concise and to confirm wording before posting unless you explicitly asked it to post.
+- Runs on Node.js (pi loads extensions via jiti) and shells out to `acli` with `child_process.execFile` — comment bodies and JQL are passed as discrete argv entries, so there is no shell-injection surface.

package/extensions/jira/acli.ts

@@ -0,0 +1,166 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Argument builders (pure — unit tested without spawning acli)
+// ---------------------------------------------------------------------------
+
+export function buildAuthStatusArgs(): string[] {
+  return ['jira', 'auth', 'status'];
+}
+
+export function buildViewArgs(key: string, fields: string): string[] {
+  return ['jira', 'workitem', 'view', key, '--fields', fields, '--json'];
+}
+
+export interface SearchInput {
+  jql: string;
+  limit: number;
+  fields?: string;
+}
+
+export function buildSearchArgs(input: SearchInput): string[] {
+  const args = ['jira', 'workitem', 'search', '--jql', input.jql, '--limit', String(input.limit)];
+  if (input.fields) {
+    args.push('--fields', input.fields);
+  }
+  args.push('--json');
+  return args;
+}
+
+export function buildCommentListArgs(key: string, limit: number): string[] {
+  return ['jira', 'workitem', 'comment', 'list', '--key', key, '--limit', String(limit), '--json'];
+}
+
+export function buildCommentCreateArgs(key: string, body: string): string[] {
+  return ['jira', 'workitem', 'comment', 'create', '--key', key, '--body', body, '--json'];
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+export interface AcliResult {
+  stdout: string;
+  stderr: string;
+}
+
+export class AcliError extends Error {
+  readonly code: 'binary_not_found' | 'not_authenticated' | 'command_failed';
+  readonly stderr: string;
+  readonly exitCode?: number;
+
+  constructor(
+    code: AcliError['code'],
+    message: string,
+    options: { stderr?: string; exitCode?: number } = {},
+  ) {
+    super(message);
+    this.name = 'AcliError';
+    this.code = code;
+    this.stderr = options.stderr ?? '';
+    this.exitCode = options.exitCode;
+  }
+}
+
+/** Recognises the auth-failure signature in acli stderr output. */
+export function looksUnauthenticated(text: string): boolean {
+  const t = text.toLowerCase();
+  return (
+    t.includes('not authenticated') ||
+    t.includes('please authenticate') ||
+    t.includes('no active session') ||
+    t.includes('auth login') ||
+    t.includes('unauthorized') ||
+    t.includes('401')
+  );
+}
+
+/**
+ * Runs the acli binary and returns stdout/stderr. Maps the common failure
+ * modes (missing binary, auth expiry) onto a typed {@link AcliError}.
+ */
+export async function runAcli(
+  bin: string,
+  args: string[],
+  signal?: AbortSignal,
+): Promise<AcliResult> {
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, {
+      signal,
+      maxBuffer: 32 * 1024 * 1024,
+      encoding: 'utf-8',
+    });
+    return { stdout, stderr };
+  } catch (err: unknown) {
+    const e = err as NodeJS.ErrnoException & { stdout?: string; stderr?: string; code?: unknown };
+
+    if (e.code === 'ENOENT') {
+      throw new AcliError(
+        'binary_not_found',
+        `Atlassian CLI not found (tried "${bin}"). Install acli and ensure it is on PATH, or set "acliPath" in .pi/jira.json.`,
+      );
+    }
+
+    const stderr = e.stderr ?? '';
+    const stdout = e.stdout ?? '';
+    const combined = `${stderr}\n${stdout}`;
+
+    if (looksUnauthenticated(combined)) {
+      throw new AcliError(
+        'not_authenticated',
+        'No authenticated Atlassian CLI session. Run `acli jira auth login` in your terminal, then retry.',
+        { stderr },
+      );
+    }
+
+    const exitCode = typeof e.code === 'number' ? e.code : undefined;
+    const detail = (stderr.trim() || stdout.trim() || e.message || 'unknown error').slice(0, 2000);
+    throw new AcliError('command_failed', `acli command failed: ${detail}`, { stderr, exitCode });
+  }
+}
+
+/**
+ * Verifies an authenticated acli session via `acli jira auth status`.
+ * Returns a flat status object rather than throwing, so the extension can
+ * surface a friendly warning without aborting startup.
+ */
+export async function checkAuth(
+  bin: string,
+  signal?: AbortSignal,
+): Promise<{ authenticated: boolean; message: string }> {
+  try {
+    const { stdout, stderr } = await runAcli(bin, buildAuthStatusArgs(), signal);
+    const text = `${stdout}\n${stderr}`.trim();
+    if (looksUnauthenticated(text)) {
+      return { authenticated: false, message: text || 'No active session.' };
+    }
+    return { authenticated: true, message: text || 'Authenticated.' };
+  } catch (err) {
+    if (err instanceof AcliError) {
+      return { authenticated: false, message: err.message };
+    }
+    return { authenticated: false, message: (err as Error).message };
+  }
+}
+
+/** Parses acli `--json` stdout, tolerating leading/trailing non-JSON noise. */
+export function parseJsonOutput<T = unknown>(stdout: string): T {
+  const trimmed = stdout.trim();
+  try {
+    return JSON.parse(trimmed) as T;
+  } catch {
+    // acli occasionally prefixes a status line before the JSON payload.
+    const start = trimmed.search(/[[{]/);
+    if (start > 0) {
+      try {
+        return JSON.parse(trimmed.slice(start)) as T;
+      } catch {
+        /* fall through */
+      }
+    }
+    throw new AcliError('command_failed', 'Could not parse acli JSON output.');
+  }
+}

package/extensions/jira/config.ts

@@ -0,0 +1,119 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Project config (.pi/jira.json)
+// ---------------------------------------------------------------------------
+
+export interface JiraProjectConfig {
+  /** Path/name of the Atlassian CLI binary. Default "acli". */
+  acliPath: string;
+  /** Default project key, used to qualify bare issue numbers and JQL. */
+  defaultProject?: string;
+  /**
+   * Comma-separated field set passed to `acli jira workitem view --fields`.
+   * Tuned for agent context (description + comments) rather than acli defaults.
+   */
+  viewFields: string;
+  /** Default max results for `jira_search`. Default 25. */
+  searchLimit: number;
+}
+
+interface RawConfig {
+  acliPath?: unknown;
+  defaultProject?: unknown;
+  viewFields?: unknown;
+  searchLimit?: unknown;
+}
+
+/** Curated field set: rich enough for context without dumping every custom field. */
+export const DEFAULT_VIEW_FIELDS =
+  'summary,issuetype,status,priority,assignee,reporter,labels,components,parent,description,comment,created,updated';
+
+export const DEFAULT_CONFIG: JiraProjectConfig = {
+  acliPath: 'acli',
+  viewFields: DEFAULT_VIEW_FIELDS,
+  searchLimit: 25,
+};
+
+/**
+ * Loads and validates `.pi/jira.json` from the project root.
+ * Returns defaults if the file does not exist. Throws on invalid JSON or
+ * invalid field types.
+ */
+export async function loadProjectConfig(cwd: string): Promise<JiraProjectConfig> {
+  const configPath = join(cwd, '.pi', 'jira.json');
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, 'utf-8');
+  } catch (err: unknown) {
+    if (err instanceof Error && 'code' in err && (err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ...DEFAULT_CONFIG };
+    }
+    throw new Error(`Failed to read ${configPath}: ${(err as Error).message}`);
+  }
+
+  let parsed: RawConfig;
+  try {
+    parsed = JSON.parse(raw) as RawConfig;
+  } catch {
+    throw new Error(`Invalid JSON in ${configPath}`);
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${configPath} must be a JSON object`);
+  }
+
+  return validateConfig(parsed, configPath);
+}
+
+function validateConfig(raw: RawConfig, configPath: string): JiraProjectConfig {
+  const config: JiraProjectConfig = { ...DEFAULT_CONFIG };
+
+  if (raw.acliPath !== undefined) {
+    if (typeof raw.acliPath !== 'string' || raw.acliPath.trim() === '') {
+      throw new Error(`${configPath}: "acliPath" must be a non-empty string`);
+    }
+    config.acliPath = raw.acliPath;
+  }
+
+  if (raw.defaultProject !== undefined) {
+    if (typeof raw.defaultProject !== 'string') {
+      throw new Error(`${configPath}: "defaultProject" must be a string`);
+    }
+    config.defaultProject = raw.defaultProject;
+  }
+
+  if (raw.viewFields !== undefined) {
+    if (typeof raw.viewFields !== 'string' || raw.viewFields.trim() === '') {
+      throw new Error(`${configPath}: "viewFields" must be a non-empty string`);
+    }
+    config.viewFields = raw.viewFields;
+  }
+
+  if (raw.searchLimit !== undefined) {
+    if (
+      typeof raw.searchLimit !== 'number' ||
+      !Number.isInteger(raw.searchLimit) ||
+      raw.searchLimit < 1
+    ) {
+      throw new Error(`${configPath}: "searchLimit" must be a positive integer`);
+    }
+    config.searchLimit = raw.searchLimit;
+  }
+
+  return config;
+}
+
+/**
+ * Qualifies a bare issue number with the default project (e.g. "123" -> "PROJ-123").
+ * Leaves already-qualified keys (containing a dash) untouched.
+ */
+export function qualifyKey(key: string, defaultProject?: string): string {
+  const trimmed = key.trim();
+  if (/^\d+$/.test(trimmed) && defaultProject) {
+    return `${defaultProject}-${trimmed}`;
+  }
+  return trimmed;
+}

package/extensions/jira/format.ts

@@ -0,0 +1,220 @@
+// ---------------------------------------------------------------------------
+// Jira JSON shapes (loose — acli surfaces the Jira REST issue shape)
+// ---------------------------------------------------------------------------
+
+interface NamedRef {
+  name?: string;
+  displayName?: string;
+}
+
+interface AdfNode {
+  type?: string;
+  text?: string;
+  content?: AdfNode[];
+}
+
+export interface JiraComment {
+  id?: string;
+  author?: NamedRef;
+  created?: string;
+  updated?: string;
+  body?: unknown;
+}
+
+export interface JiraIssue {
+  key?: string;
+  fields?: {
+    summary?: string;
+    issuetype?: NamedRef;
+    status?: NamedRef;
+    priority?: NamedRef;
+    assignee?: NamedRef | null;
+    reporter?: NamedRef | null;
+    labels?: string[];
+    components?: NamedRef[];
+    parent?: JiraIssue;
+    description?: unknown;
+    created?: string;
+    updated?: string;
+    comment?: { comments?: JiraComment[]; total?: number };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ADF (Atlassian Document Format) → plain text
+// ---------------------------------------------------------------------------
+
+/** Flattens an ADF document, plain string, or null into readable text. */
+export function adfToText(value: unknown): string {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object') return String(value);
+
+  const node = value as AdfNode;
+  const parts: string[] = [];
+
+  const walk = (n: AdfNode): void => {
+    if (!n || typeof n !== 'object') return;
+    if (typeof n.text === 'string') parts.push(n.text);
+    if (n.type === 'hardBreak') parts.push('\n');
+    if (Array.isArray(n.content)) {
+      for (const child of n.content) walk(child);
+      // Paragraph / list-item boundaries become line breaks.
+      if (n.type === 'paragraph' || n.type === 'listItem' || n.type === 'heading') {
+        parts.push('\n');
+      }
+    }
+  };
+
+  walk(node);
+  return parts
+    .join('')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function name(ref: NamedRef | null | undefined, fallback = '—'): string {
+  return ref?.displayName ?? ref?.name ?? fallback;
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max).trimEnd()}…`;
+}
+
+// ---------------------------------------------------------------------------
+// Single work item
+// ---------------------------------------------------------------------------
+
+/** Compact inline digest returned to the model (cheap on tokens). */
+export function formatWorkItemDigest(issue: JiraIssue, fullFile?: string): string {
+  const f = issue.fields ?? {};
+  const lines: string[] = [];
+  lines.push(`${issue.key ?? '(no key)'} — ${f.summary ?? '(no summary)'}`);
+  lines.push(
+    `Type: ${name(f.issuetype)} | Status: ${name(f.status)} | Priority: ${name(f.priority)} | Assignee: ${name(f.assignee)}`,
+  );
+  if (f.labels?.length) lines.push(`Labels: ${f.labels.join(', ')}`);
+  if (f.parent?.key) lines.push(`Parent: ${f.parent.key} — ${f.parent.fields?.summary ?? ''}`);
+
+  const desc = adfToText(f.description);
+  if (desc) lines.push('', truncate(desc, 600));
+
+  const comments = f.comment?.comments ?? [];
+  const total = f.comment?.total ?? comments.length;
+  if (total > 0) lines.push('', `Comments: ${total} (full thread in file)`);
+
+  if (fullFile) lines.push('', `Full ticket written to: ${fullFile}`);
+  return lines.join('\n');
+}
+
+/** Full, untruncated markdown written to a temp file for the agent to read. */
+export function formatWorkItemFull(issue: JiraIssue): string {
+  const f = issue.fields ?? {};
+  const lines: string[] = [];
+  lines.push(`# ${issue.key ?? ''} — ${f.summary ?? ''}`, '');
+  lines.push(`- Type: ${name(f.issuetype)}`);
+  lines.push(`- Status: ${name(f.status)}`);
+  lines.push(`- Priority: ${name(f.priority)}`);
+  lines.push(`- Assignee: ${name(f.assignee)}`);
+  lines.push(`- Reporter: ${name(f.reporter)}`);
+  if (f.labels?.length) lines.push(`- Labels: ${f.labels.join(', ')}`);
+  if (f.components?.length)
+    lines.push(`- Components: ${f.components.map((c) => name(c)).join(', ')}`);
+  if (f.parent?.key) lines.push(`- Parent: ${f.parent.key} — ${f.parent.fields?.summary ?? ''}`);
+  if (f.created) lines.push(`- Created: ${f.created}`);
+  if (f.updated) lines.push(`- Updated: ${f.updated}`);
+
+  const desc = adfToText(f.description);
+  lines.push('', '## Description', '', desc || '_(no description)_');
+
+  const comments = f.comment?.comments ?? [];
+  if (comments.length > 0) {
+    lines.push('', `## Comments (${f.comment?.total ?? comments.length})`, '');
+    lines.push(formatComments(comments));
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Comments
+// ---------------------------------------------------------------------------
+
+export function formatComments(comments: JiraComment[]): string {
+  if (comments.length === 0) return '_(no comments)_';
+  return comments
+    .map((c) => {
+      const who = name(c.author);
+      const when = c.updated ?? c.created ?? '';
+      const body = adfToText(c.body);
+      return `### ${who}${when ? ` · ${when}` : ''}${c.id ? ` · #${c.id}` : ''}\n\n${body}`;
+    })
+    .join('\n\n');
+}
+
+/**
+ * Compact comment digest for inline tool output: most recent few comments,
+ * each body truncated. The full thread lives in the temp file.
+ */
+export function formatCommentsDigest(
+  comments: JiraComment[],
+  key: string,
+  fullFile?: string,
+  preview = 3,
+): string {
+  if (comments.length === 0) return `${key}: no comments.`;
+  const recent = comments.slice(-preview);
+  const lines = [`${key}: ${comments.length} comment(s). Most recent ${recent.length}:`, ''];
+  for (const c of recent) {
+    const who = name(c.author);
+    const when = c.updated ?? c.created ?? '';
+    lines.push(`- ${who}${when ? ` · ${when}` : ''}: ${truncate(adfToText(c.body), 200)}`);
+  }
+  if (fullFile) lines.push('', `Full thread written to: ${fullFile}`);
+  return lines.join('\n');
+}
+
+/** Full, untruncated comment thread written to a temp file. */
+export function formatCommentsFull(comments: JiraComment[], key: string): string {
+  return `# Comments — ${key} (${comments.length})\n\n${formatComments(comments)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Search results
+// ---------------------------------------------------------------------------
+
+/** Pulls the issues array out of acli's search payload (shape varies). */
+export function extractIssues(payload: unknown): JiraIssue[] {
+  if (Array.isArray(payload)) return payload as JiraIssue[];
+  if (payload && typeof payload === 'object') {
+    const obj = payload as Record<string, unknown>;
+    for (const key of ['issues', 'workItems', 'results', 'data']) {
+      if (Array.isArray(obj[key])) return obj[key] as JiraIssue[];
+    }
+  }
+  return [];
+}
+
+export function formatSearchDigest(issues: JiraIssue[], fullFile?: string): string {
+  if (issues.length === 0) return 'No matching work items.';
+  const lines = issues.map((issue) => {
+    const f = issue.fields ?? {};
+    return `- ${issue.key ?? '?'} [${name(f.status, '?')}] ${truncate(f.summary ?? '', 100)}${
+      f.assignee ? ` (@${name(f.assignee)})` : ''
+    }`;
+  });
+  const out = [`${issues.length} work item(s):`, ...lines];
+  if (fullFile) out.push('', `Full results (with descriptions) written to: ${fullFile}`);
+  return out.join('\n');
+}
+
+/** Full search results written to a temp file — one rendered block per item. */
+export function formatSearchFull(issues: JiraIssue[]): string {
+  if (issues.length === 0) return 'No matching work items.';
+  return [
+    `# Search results (${issues.length})`,
+    '',
+    ...issues.map((issue) => formatWorkItemFull(issue)),
+  ].join('\n\n---\n\n');
+}

package/extensions/jira/index.ts

@@ -0,0 +1,325 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { type JiraProjectConfig, DEFAULT_CONFIG, loadProjectConfig, qualifyKey } from './config.js';
+import {
+  AcliError,
+  buildCommentCreateArgs,
+  buildCommentListArgs,
+  buildSearchArgs,
+  buildViewArgs,
+  checkAuth,
+  parseJsonOutput,
+  runAcli,
+} from './acli.js';
+import {
+  type JiraComment,
+  type JiraIssue,
+  extractIssues,
+  formatCommentsDigest,
+  formatCommentsFull,
+  formatSearchDigest,
+  formatSearchFull,
+  formatWorkItemDigest,
+  formatWorkItemFull,
+} from './format.js';
+import { writeContextFile } from './output.js';
+
+const TOOL_GUIDELINES = [
+  'Use `jira_view` to pull a Jira ticket into context before working on it. Pass the key (e.g. "PROJ-123"); a bare number works when a defaultProject is set in .pi/jira.json.',
+  'The inline `jira_view` output is a compact digest. The full ticket — complete description and every comment — is written to a temp file whose path is in the response. To read the whole thing, use the `read` tool on that file instead of re-fetching.',
+  'Use `jira_search` with JQL to find tickets (e.g. "project = PROJ AND status = \'In Progress\'", "assignee = currentUser()"). It returns a compact list and writes the full results (with descriptions) to a temp file whose path is in the response.',
+  "Use `jira_comments` to read a ticket's comment thread. The inline output is a digest of the most recent comments; the complete thread is written to a temp file. Comment bodies and ticket fields can be truncated inline, so when you need the full text, `read` the temp file path rather than re-fetching.",
+  'Use `jira_comment` to post a comment. Keep comments concise and factual — a short status update or finding, not a wall of text. Unless the user explicitly asked you to post, confirm the exact wording with them first; comments are visible to the whole team and cannot be unsent cleanly.',
+  'All tools require an authenticated Atlassian CLI session. If a tool reports it is not authenticated, tell the user to run `acli jira auth login` in their terminal.',
+];
+
+export default function jiraExtension(pi: ExtensionAPI) {
+  let config: JiraProjectConfig = { ...DEFAULT_CONFIG };
+
+  async function ensureConfig(cwd?: string): Promise<JiraProjectConfig> {
+    if (cwd) {
+      try {
+        config = await loadProjectConfig(cwd);
+      } catch {
+        /* keep last-known / defaults */
+      }
+    }
+    return config;
+  }
+
+  function acliFailure(err: unknown) {
+    if (err instanceof AcliError) {
+      return {
+        content: [{ type: 'text' as const, text: `❌ ${err.message}` }],
+        details: { error: err.code, exitCode: err.exitCode } as Record<string, unknown>,
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: 'text' as const, text: `❌ ${(err as Error).message}` }],
+      details: { error: 'unknown' } as Record<string, unknown>,
+      isError: true,
+    };
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    config = await loadProjectConfig(ctx.cwd).catch(() => ({ ...DEFAULT_CONFIG }));
+    const auth = await checkAuth(config.acliPath);
+    if (!auth.authenticated) {
+      ctx.ui.notify(
+        `Jira: no authenticated Atlassian CLI session. Run \`acli jira auth login\` to enable Jira tools. (${auth.message})`,
+        'warning',
+      );
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // jira_view
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: 'jira_view',
+    label: 'Jira View Ticket',
+    description:
+      'Fetch a Jira work item (description + comments) for context via the Atlassian CLI. Returns a compact digest inline and writes the full ticket to a temp file.',
+    promptSnippet: 'Pull a Jira ticket into context (description + comments)',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: Type.Object({
+      key: Type.String({
+        description:
+          'Work item key (e.g. "PROJ-123"). A bare number works if defaultProject is set.',
+      }),
+      fields: Type.Optional(
+        Type.String({
+          description:
+            'Comma-separated acli field set to override the configured default (e.g. "summary,status,comment", "*all").',
+        }),
+      ),
+    }),
+    async execute(
+      _id: string,
+      params: { key: string; fields?: string },
+      signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd: string },
+    ) {
+      const cfg = await ensureConfig(ctx?.cwd);
+      const key = qualifyKey(params.key, cfg.defaultProject);
+      try {
+        const { stdout } = await runAcli(
+          cfg.acliPath,
+          buildViewArgs(key, params.fields ?? cfg.viewFields),
+          signal,
+        );
+        const issue = parseJsonOutput<JiraIssue>(stdout);
+        const full = formatWorkItemFull(issue);
+        let file: string | undefined;
+        try {
+          file = await writeContextFile(full, key.toLowerCase());
+        } catch {
+          file = undefined;
+        }
+        return {
+          content: [{ type: 'text' as const, text: formatWorkItemDigest(issue, file) }],
+          details: { key, contextFile: file } as Record<string, unknown>,
+        };
+      } catch (err) {
+        return acliFailure(err);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // jira_search
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: 'jira_search',
+    label: 'Jira Search',
+    description:
+      'Search Jira work items with JQL via the Atlassian CLI. Returns a compact list of matching keys, statuses, and summaries.',
+    promptSnippet: 'Search Jira work items with JQL',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: Type.Object({
+      jql: Type.String({
+        description:
+          'JQL query (e.g. "project = PROJ AND status = \'In Progress\'", "assignee = currentUser() ORDER BY updated DESC").',
+      }),
+      limit: Type.Optional(
+        Type.Number({
+          description: 'Max results (1-100). Defaults to searchLimit from .pi/jira.json or 25.',
+          minimum: 1,
+          maximum: 100,
+        }),
+      ),
+    }),
+    async execute(
+      _id: string,
+      params: { jql: string; limit?: number },
+      signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd: string },
+    ) {
+      const cfg = await ensureConfig(ctx?.cwd);
+      try {
+        const { stdout } = await runAcli(
+          cfg.acliPath,
+          buildSearchArgs({ jql: params.jql, limit: params.limit ?? cfg.searchLimit }),
+          signal,
+        );
+        const issues = extractIssues(parseJsonOutput(stdout));
+        let file: string | undefined;
+        if (issues.length > 0) {
+          try {
+            file = await writeContextFile(formatSearchFull(issues), 'search');
+          } catch {
+            file = undefined;
+          }
+        }
+        return {
+          content: [{ type: 'text' as const, text: formatSearchDigest(issues, file) }],
+          details: {
+            count: issues.length,
+            keys: issues.map((i) => i.key).filter(Boolean),
+            contextFile: file,
+          } as Record<string, unknown>,
+        };
+      } catch (err) {
+        return acliFailure(err);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // jira_comments
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: 'jira_comments',
+    label: 'Jira List Comments',
+    description: 'List the comment thread on a Jira work item via the Atlassian CLI.',
+    promptSnippet: 'Read the comment thread on a Jira ticket',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: Type.Object({
+      key: Type.String({ description: 'Work item key (e.g. "PROJ-123").' }),
+      limit: Type.Optional(
+        Type.Number({
+          description: 'Max comments to return (1-100). Default 50.',
+          minimum: 1,
+          maximum: 100,
+        }),
+      ),
+    }),
+    async execute(
+      _id: string,
+      params: { key: string; limit?: number },
+      signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd: string },
+    ) {
+      const cfg = await ensureConfig(ctx?.cwd);
+      const key = qualifyKey(params.key, cfg.defaultProject);
+      try {
+        const { stdout } = await runAcli(
+          cfg.acliPath,
+          buildCommentListArgs(key, params.limit ?? 50),
+          signal,
+        );
+        const payload = parseJsonOutput<{ comments?: JiraComment[] } | JiraComment[]>(stdout);
+        const comments = Array.isArray(payload) ? payload : (payload.comments ?? []);
+        let file: string | undefined;
+        if (comments.length > 0) {
+          try {
+            file = await writeContextFile(
+              formatCommentsFull(comments, key),
+              `${key.toLowerCase()}-comments`,
+            );
+          } catch {
+            file = undefined;
+          }
+        }
+        return {
+          content: [{ type: 'text' as const, text: formatCommentsDigest(comments, key, file) }],
+          details: { key, count: comments.length, contextFile: file } as Record<string, unknown>,
+        };
+      } catch (err) {
+        return acliFailure(err);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // jira_comment (write)
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: 'jira_comment',
+    label: 'Jira Add Comment',
+    description:
+      'Post a comment to a Jira work item via the Atlassian CLI. Keep comments concise and factual. Visible to the whole team.',
+    promptSnippet: 'Post a concise comment to a Jira ticket',
+    promptGuidelines: TOOL_GUIDELINES,
+    parameters: Type.Object({
+      key: Type.String({ description: 'Work item key (e.g. "PROJ-123").' }),
+      body: Type.String({
+        description: 'Comment text (plain text). Keep it short and to the point.',
+      }),
+    }),
+    async execute(
+      _id: string,
+      params: { key: string; body: string },
+      signal?: AbortSignal,
+      _onUpdate?: unknown,
+      ctx?: { cwd: string },
+    ) {
+      const cfg = await ensureConfig(ctx?.cwd);
+      const key = qualifyKey(params.key, cfg.defaultProject);
+      if (!params.body.trim()) {
+        return {
+          content: [{ type: 'text' as const, text: '❌ Comment body is empty.' }],
+          details: { error: 'empty_body' } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+      try {
+        await runAcli(cfg.acliPath, buildCommentCreateArgs(key, params.body), signal);
+        return {
+          content: [{ type: 'text' as const, text: `✅ Comment added to ${key}.` }],
+          details: { key } as Record<string, unknown>,
+        };
+      } catch (err) {
+        return acliFailure(err);
+      }
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // /jira status command
+  // -------------------------------------------------------------------------
+  pi.registerCommand('jira', {
+    description: 'Show Jira (Atlassian CLI) configuration and auth status',
+    handler: async (
+      _args: string,
+      ctx: {
+        cwd: string;
+        hasUI: boolean;
+        ui: { notify(message: string, level: 'info' | 'warning' | 'error'): void };
+      },
+    ) => {
+      const cfg = await ensureConfig(ctx.cwd);
+      const auth = await checkAuth(cfg.acliPath);
+      const lines = [
+        'Jira Extension Status',
+        '',
+        `Auth: ${auth.authenticated ? '✅ Authenticated' : '❌ Not authenticated'}`,
+        `  ${auth.message.split('\n')[0]}`,
+        '',
+        'Config (.pi/jira.json):',
+        `  acli path: ${cfg.acliPath}`,
+        `  Default project: ${cfg.defaultProject ?? '(not set)'}`,
+        `  View fields: ${cfg.viewFields}`,
+        `  Search limit: ${cfg.searchLimit}`,
+      ];
+      if (!auth.authenticated) {
+        lines.push('', 'Run `acli jira auth login` in your terminal to authenticate.');
+      }
+      if (ctx.hasUI) ctx.ui.notify(lines.join('\n'), 'info');
+    },
+  });
+}

package/extensions/jira/output.ts

@@ -0,0 +1,17 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Writes the full (untruncated) ticket context to a temp file the agent can
+ * read with the `read` tool, keeping the inline tool response compact.
+ *
+ * `prefix` controls the filename stem (e.g. "ticket" → `ticket-<ts>.md`).
+ * Returns the absolute path to the written file.
+ */
+export async function writeContextFile(content: string, prefix = 'ticket'): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'pi-jira-'));
+  const path = join(dir, `${prefix}-${Date.now()}.md`);
+  await writeFile(path, content, 'utf-8');
+  return path;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dreki-gg/pi-jira",
+  "version": "0.2.0",
+  "description": "Jira tools for pi via an authenticated Atlassian CLI (acli) session — pull ticket context and write concise comments",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "jira",
+    "atlassian",
+    "acli"
+  ],
+  "author": "Juan Albarran <jalbarrandev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dreki-gg/pi-extensions",
+    "directory": "packages/jira"
+  },
+  "type": "module",
+  "files": [
+    "extensions",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "oxlint extensions test",
+    "format": "oxfmt --write extensions test",
+    "format:check": "oxfmt --check extensions test"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/jira"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "24",
+    "bun-types": "^1.3.14",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "typescript": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  }
+}