haitask 0.3.1 → 0.3.5

package/README.md

@@ -33,6 +33,7 @@ haitask init
 
 Pick a target (1 = Jira, 2 = Trello, 3 = Linear) and answer the prompts. You get a `.haitaskrc` and an optional `.env` template.  
 **Quick mode:** `haitask init --quick` — fewer questions, sensible defaults.
+**Preset mode:** `haitask init --preset jira|trello|linear` — non-interactive starter config.
 
 **2. Add API keys**  
 In the generated `.env`, set the keys for your target and AI provider:
@@ -53,6 +54,7 @@ haitask run
 ```
 
 To try without creating a task: `haitask run --dry`.
+For machine-readable output: `haitask run --dry --json`.
 
 ---
 
@@ -62,14 +64,59 @@ To try without creating a task: `haitask run --dry`.
 |---------|-------------|
 | `haitask init` | Interactive setup: target, AI, rules → writes `.haitaskrc` and optional `.env` |
 | `haitask init --quick` | Minimal prompts: target + required fields only; defaults for AI, branches, prefixes |
+| `haitask init --preset <target>` | Non-interactive preset config for `jira`, `trello`, or `linear` |
+| `haitask check` | Validate `.haitaskrc` + required env keys without running the pipeline |
 | `haitask run` | Creates a task from the latest commit (Jira / Trello / Linear) |
 | `haitask run --dry` | Same flow, but does not create a task |
+| `haitask run --json` | Print machine-readable JSON output (works with `--dry`) |
 | `haitask run --commits N` | Combine the last N commits into one task (e.g. `--commits 3`) |
 | `haitask run --type <type>` | (Jira only) Override issue type for this run (Task, Bug, Story) |
 | `haitask run --status <status>` | (Jira only) Override status after create (Done, "To Do", etc.) |
 
 ---
 
+## JSON output (automation)
+
+Use `--json` when integrating with CI/CD or scripts. This guarantees a parseable payload on both success and failure.
+
+```bash
+haitask run --dry --json
+```
+
+Success shape:
+
+```json
+{
+  "ok": true,
+  "dry": true,
+  "skipped": false,
+  "commented": false,
+  "key": null,
+  "url": null,
+  "payload": {
+    "title": "Add login validation",
+    "description": "..."
+  },
+  "commit": {
+    "branch": "main",
+    "commitHash": "abc123...",
+    "repoName": "my-repo",
+    "count": 1
+  }
+}
+```
+
+Failure shape:
+
+```json
+{
+  "ok": false,
+  "error": "Config error: Config not found ..."
+}
+```
+
+---
+
 ## Configuration
 
 - **`.haitaskrc`** — `target` (jira / trello / linear), target-specific options, `ai` (provider, model), `rules` (allowedBranches, commitPrefixes).
@@ -93,7 +140,62 @@ To try without creating a task: `haitask run --dry`.
 
 - **Global:** `npm install -g haitask` → run `haitask init` once per repo, then `haitask run` after commits.
 - **Per project:** `npm install haitask --save-dev` → `npx haitask run`.
-- **CI / scripts:** Run `npx haitask run` from the repo root; ensure `.haitaskrc` and env vars are available.
+- **CI / scripts:** Run `npx haitask run --dry --json` from the repo root, parse `ok`, and fail pipeline when `ok === false`.
+
+Example (bash + `jq`):
+
+```bash
+out="$(npx haitask run --dry --json)"
+echo "$out"
+test "$(echo "$out" | jq -r '.ok')" = "true"
+```
+
+---
+
+## GitHub Actions Integration
+
+Add this workflow to `.github/workflows/haitask.yml` for automatic task creation:
+
+```yaml
+name: Create Task from Commit
+
+on:
+  push:
+    branches: [ main, develop ]
+
+jobs:
+  create-task:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+        
+    - name: Install HAITASK
+      run: npm install -g haitask
+      
+    - name: Create task from latest commit
+      env:
+        GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+        # Add your target-specific keys:
+        # JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+        # TRELLO_TOKEN: ${{ secrets.TRELLO_TOKEN }}
+        # LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+      run: |
+        if [ -f ".haitaskrc" ]; then
+          haitask run
+        fi
+```
+
+**Setup:**
+1. Copy the workflow to your repo
+2. Add required secrets to GitHub repo settings
+3. Configure `.haitaskrc` in your project root
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "haitask",
-  "version": "0.3.1",
-  "description": "HAITASK — AI-powered task creation from Git commits. Creates issues in Jira, Trello, or Linear from your latest commit message and branch.",
+  "version": "0.3.5",
+  "description": "HAITASK \u2014 AI-powered task creation from Git commits. Creates issues in Jira, Trello, or Linear from your latest commit message and branch.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -44,4 +44,4 @@
     "dotenv": "^16.4.5",
     "execa": "^9.5.2"
   }
-}
+}

package/src/ai/deepseek.js

@@ -9,7 +9,7 @@ import { buildPrompt, parseTaskPayload } from './utils.js';
 const DEEPSEEK_API_URL = 'https://api.deepseek.com/v1/chat/completions';
 
 /**
- * Call Deepseek and return task payload for Jira.
+ * Call Deepseek and return task payload for the configured target.
  * @param {{ message: string, branch: string, repoName: string }} commitData
  * @param {{ ai: { model?: string } }} config
  * @returns {Promise<{ title: string, description: string, labels: string[] }>}
@@ -21,7 +21,7 @@ export async function generateDeepseek(commitData, config) {
   }
 
   const model = config?.ai?.model || 'deepseek-chat';
-  const { system, user } = buildPrompt(commitData);
+  const { system, user } = buildPrompt(commitData, config?.target);
 
   const response = await fetch(DEEPSEEK_API_URL, {
     method: 'POST',
@@ -47,7 +47,7 @@ export async function generateDeepseek(commitData, config) {
   const data = await response.json();
   const content = data?.choices?.[0]?.message?.content;
   if (typeof content !== 'string') {
-    throw new Error('Deepseek response missing choices[0].message.content');
+    throw new TypeError('Deepseek response missing choices[0].message.content');
   }
 
   return parseTaskPayload(content.trim());

package/src/ai/groq.js

@@ -9,7 +9,7 @@ import { buildPrompt, parseTaskPayload } from './utils.js';
 const GROQ_API_URL = 'https://api.groq.com/openai/v1/chat/completions';
 
 /**
- * Call Groq and return task payload for Jira.
+ * Call Groq and return task payload for the configured target.
  * @param {{ message: string, branch: string, repoName: string }} commitData
  * @param {{ ai: { model?: string } }} config
  * @returns {Promise<{ title: string, description: string, labels: string[] }>}
@@ -23,7 +23,7 @@ export async function generateGroq(commitData, config) {
   }
 
   const model = config?.ai?.model || 'llama-3.1-8b-instant';
-  const { system, user } = buildPrompt(commitData);
+  const { system, user } = buildPrompt(commitData, config?.target);
 
   const response = await fetch(GROQ_API_URL, {
     method: 'POST',
@@ -49,7 +49,7 @@ export async function generateGroq(commitData, config) {
   const data = await response.json();
   const content = data?.choices?.[0]?.message?.content;
   if (typeof content !== 'string') {
-    throw new Error('Groq response missing choices[0].message.content');
+    throw new TypeError('Groq response missing choices[0].message.content');
   }
 
   return parseTaskPayload(content.trim());

package/src/ai/openai.js

@@ -7,7 +7,7 @@ import { buildPrompt, parseTaskPayload } from './utils.js';
 const OPENAI_API_URL = 'https://api.openai.com/v1/chat/completions';
 
 /**
- * Call OpenAI and return task payload for Jira.
+ * Call OpenAI and return task payload for the configured target.
  * @param {{ message: string, branch: string, repoName: string }} commitData
  * @param {{ ai: { model?: string } }} config
  * @returns {Promise<{ title: string, description: string, labels: string[] }>}
@@ -19,7 +19,7 @@ export async function generateOpenAI(commitData, config) {
   }
 
   const model = config?.ai?.model || 'gpt-4o-mini';
-  const { system, user } = buildPrompt(commitData);
+  const { system, user } = buildPrompt(commitData, config?.target);
 
   const response = await fetch(OPENAI_API_URL, {
     method: 'POST',
@@ -45,7 +45,7 @@ export async function generateOpenAI(commitData, config) {
   const data = await response.json();
   const content = data?.choices?.[0]?.message?.content;
   if (typeof content !== 'string') {
-    throw new Error('OpenAI response missing choices[0].message.content');
+    throw new TypeError('OpenAI response missing choices[0].message.content');
   }
 
   return parseTaskPayload(content.trim());

package/src/ai/utils.js

@@ -7,27 +7,39 @@ const CONVENTIONAL_PREFIXES = /^(feat|fix|chore|docs|style|refactor|test|build|c
 /**
  * Build system + user prompt from commit data.
  * @param {{ message: string, branch: string, repoName: string }} commitData
+ * @param {string} [target='jira']
  * @returns {{ system: string, user: string }}
  */
 const BATCH_SEP = '\n\n---\n\n';
 
-export function buildPrompt(commitData) {
+const TARGET_META = {
+  jira: { displayName: 'Jira', workItem: 'issue', priorityField: true },
+  trello: { displayName: 'Trello', workItem: 'card', priorityField: false },
+  linear: { displayName: 'Linear', workItem: 'issue', priorityField: true },
+};
+
+export function buildPrompt(commitData, target = 'jira') {
   const { message, branch, repoName } = commitData;
   const isBatch = message.includes(BATCH_SEP);
+  const normalizedTarget = (target || 'jira').toLowerCase();
+  const meta = TARGET_META[normalizedTarget] || TARGET_META.jira;
   const batchHint = isBatch
     ? ' The user input may contain multiple commits separated by "---"; produce one task that summarizes all of them.\n\n'
     : '';
-  const system = `You generate a Jira task from a Git commit. Reply with a single JSON object only, no markdown or extra text.
+  const priorityRule = meta.priorityField
+    ? '- "priority": One of: "Highest", "High", "Medium", "Low", "Lowest". Infer from commit message (e.g. "urgent", "critical", "hotfix" → High; "minor", "tweak" → Low; unclear → "Medium"). Default to "Medium" if unsure.'
+    : '- "priority": Still provide one of "Highest", "High", "Medium", "Low", "Lowest". Some targets may not have a native priority field; it can be used for description context.';
+  const system = `You generate a ${meta.displayName} ${meta.workItem} from a Git commit. Reply with a single JSON object only, no markdown or extra text.
 ${batchHint}Keys:
-- "title": Short, formal Jira task summary (professional wording). Do NOT copy the commit message verbatim. Rewrite as a clear, formal task title suitable for Jira (e.g. "Add user login validation" not "test login stuff"). Do NOT include prefixes like feat:, fix:, chore: in the title.
-- "description": Detailed description in plain language, suitable for Jira. Expand and formalize the intent of the commit; do not just paste the commit message.
+- "title": Short, formal ${meta.displayName} ${meta.workItem} summary (professional wording). Do NOT copy the commit message verbatim. Rewrite as a clear, formal title. Do NOT include prefixes like feat:, fix:, chore: in the title.
+- "description": Detailed description in plain language, suitable for ${meta.displayName}. Expand and formalize the intent of the commit; do not just paste the commit message.
 - "labels": Array of strings, e.g. ["auto", "commit"].
-- "priority": One of: "Highest", "High", "Medium", "Low", "Lowest". Infer from commit message (e.g. "urgent", "critical", "hotfix" → High; "minor", "tweak" → Low; unclear → "Medium"). Default to "Medium" if unsure.`;
+${priorityRule}`;
   const user = `Repo: ${repoName}\nBranch: ${branch}\nCommit message:\n${message}\n\nGenerate the JSON object.`;
   return { system, user };
 }
 
-const VALID_PRIORITIES = ['Highest', 'High', 'Medium', 'Low', 'Lowest'];
+const VALID_PRIORITIES = new Set(['Highest', 'High', 'Medium', 'Low', 'Lowest']);
 
 /**
  * Parse and validate AI response. Expects { title, description, labels, priority? }.
@@ -43,15 +55,15 @@ export function parseTaskPayload(raw) {
     throw new Error(`AI response is not valid JSON: ${err.message}`);
   }
   if (typeof obj.title !== 'string' || typeof obj.description !== 'string') {
-    throw new Error('AI response missing or invalid title/description (must be strings).');
+    throw new TypeError('AI response missing or invalid title/description (must be strings).');
   }
   if (!Array.isArray(obj.labels)) {
-    throw new Error('AI response labels must be an array of strings.');
+    throw new TypeError('AI response labels must be an array of strings.');
   }
   const labels = obj.labels.filter((l) => typeof l === 'string');
   const rawTitle = (obj.title || '').trim();
   const title = rawTitle.replace(CONVENTIONAL_PREFIXES, '').trim() || rawTitle;
   const rawPriority = (obj.priority || 'Medium').trim();
-  const priority = VALID_PRIORITIES.includes(rawPriority) ? rawPriority : 'Medium';
+  const priority = VALID_PRIORITIES.has(rawPriority) ? rawPriority : 'Medium';
   return { title, description: obj.description.trim(), labels, priority };
 }

package/src/backend/index.js

@@ -1,11 +1,12 @@
 /**
  * Backend abstraction: one createTask(payload, config) for all targets (Jira, Trello, …).
- * Dispatches to the right adapter based on config.target.
+ * Dispatches to the right adapter based on config.target. Wraps adapter calls with retry (5xx, 429, network).
  */
 
 import { createIssue, addComment as jiraAddComment } from '../jira/client.js';
 import { VALID_TARGETS } from '../config/constants.js';
 import { buildJiraUrl } from '../utils/urls.js';
+import { withRetry } from '../utils/retry.js';
 
 /**
  * Add a comment to an existing issue/card (link-to-existing feature).
@@ -19,16 +20,13 @@ export async function addComment(message, issueKey, config) {
   if (!VALID_TARGETS.includes(target)) {
     throw new Error(`Unknown target: "${target}". Supported: ${VALID_TARGETS.join(', ')}.`);
   }
-  if (target === 'jira') return jiraAddComment(issueKey, message, config);
-  if (target === 'trello') {
-    const { addComment: trelloAddComment } = await import('../trello/client.js');
-    return trelloAddComment(issueKey, message, config);
-  }
-  if (target === 'linear') {
-    const { addComment: linearAddComment } = await import('../linear/client.js');
-    return linearAddComment(issueKey, message, config);
-  }
-  throw new Error(`Target "${target}" has no addComment adapter.`);
+  const run = () => {
+    if (target === 'jira') return jiraAddComment(issueKey, message, config);
+    if (target === 'trello') return import('../trello/client.js').then((m) => m.addComment(issueKey, message, config));
+    if (target === 'linear') return import('../linear/client.js').then((m) => m.addComment(issueKey, message, config));
+    throw new Error(`Target "${target}" has no addComment adapter.`);
+  };
+  return withRetry(run);
 }
 
 /**
@@ -44,20 +42,20 @@ export async function createTask(payload, config) {
     throw new Error(`Unknown target: "${target}". Supported: ${VALID_TARGETS.join(', ')}.`);
   }
 
-  if (target === 'jira') {
-    const { key } = await createIssue(payload, config);
-    return { key, url: buildJiraUrl(config, key) };
-  }
-
-  if (target === 'trello') {
-    const { createTask: createTrelloTask } = await import('../trello/client.js');
-    return createTrelloTask(payload, config);
-  }
-
-  if (target === 'linear') {
-    const { createTask: createLinearTask } = await import('../linear/client.js');
-    return createLinearTask(payload, config);
-  }
-
-  throw new Error(`Target "${target}" has no adapter.`);
+  const run = async () => {
+    if (target === 'jira') {
+      const { key } = await createIssue(payload, config);
+      return { key, url: buildJiraUrl(config, key) };
+    }
+    if (target === 'trello') {
+      const { createTask: createTrelloTask } = await import('../trello/client.js');
+      return createTrelloTask(payload, config);
+    }
+    if (target === 'linear') {
+      const { createTask: createLinearTask } = await import('../linear/client.js');
+      return createLinearTask(payload, config);
+    }
+    throw new Error(`Target "${target}" has no adapter.`);
+  };
+  return withRetry(run);
 }

package/src/commands/check.js

@@ -0,0 +1,31 @@
+/**
+ * haitask check — Validate config + env only (no pipeline).
+ */
+
+import { loadConfig } from '../config/load.js';
+import { validateEnv } from '../config/init.js';
+import { getEnvPaths } from '../config/env-loader.js';
+
+export function runCheck() {
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    console.error('Config error:', err.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { valid, missing } = validateEnv(process.cwd(), config);
+  if (!valid) {
+    console.error('Missing env keys:', missing.join(', '));
+    console.log('Env is read from:', getEnvPaths().join(', '));
+    process.exitCode = 1;
+    return;
+  }
+
+  const target = (config?.target || 'jira').toLowerCase();
+  const provider = (config?.ai?.provider || 'groq').toLowerCase();
+  console.log(`Config OK. Target: ${target}. AI: ${provider}.`);
+  console.log('Env OK.');
+}

package/src/commands/init.js

@@ -7,6 +7,7 @@ import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { validateEnv } from '../config/init.js';
 import { loadConfig } from '../config/load.js';
+import { VALID_TARGETS } from '../config/constants.js';
 
 const DEFAULT_MODELS = { groq: 'llama-3.1-8b-instant', deepseek: 'deepseek-chat', openai: 'gpt-4o-mini' };
 
@@ -136,8 +137,79 @@ const DEFAULT_RULES = {
 };
 const DEFAULT_AI = { provider: 'groq', model: DEFAULT_MODELS.groq };
 
+function normalizePresetTarget(preset) {
+  const target = (preset || '').trim().toLowerCase();
+  if (!target) return null;
+  if (!VALID_TARGETS.includes(target)) return '__invalid__';
+  return target;
+}
+
+function buildPresetConfig(target) {
+  if (target === 'trello') {
+    return {
+      target: 'trello',
+      trello: { listId: 'YOUR_TRELLO_LIST_ID' },
+      ai: DEFAULT_AI,
+      rules: DEFAULT_RULES,
+    };
+  }
+  if (target === 'linear') {
+    return {
+      target: 'linear',
+      linear: { teamId: 'YOUR_LINEAR_TEAM_ID' },
+      ai: DEFAULT_AI,
+      rules: DEFAULT_RULES,
+    };
+  }
+  return {
+    target: 'jira',
+    jira: {
+      baseUrl: 'https://your-domain.atlassian.net',
+      projectKey: 'PROJ',
+      issueType: 'Task',
+      transitionToStatus: 'Done',
+    },
+    ai: DEFAULT_AI,
+    rules: DEFAULT_RULES,
+  };
+}
+
+async function buildInteractiveConfig(rl, quick) {
+  const targetAnswer = await question(rl, 'Target: 1 = Jira, 2 = Trello, 3 = Linear', '1');
+  const targetMap = { '1': 'jira', '2': 'trello', '3': 'linear' };
+  const target = targetMap[targetAnswer] || 'jira';
+
+  let rules;
+  let ai;
+  if (quick) {
+    rules = DEFAULT_RULES;
+    ai = DEFAULT_AI;
+  } else {
+    const aiProvider = await question(rl, 'AI provider (groq | deepseek | openai)', 'groq');
+    const allowedBranchesStr = await question(rl, 'Allowed branches (comma-separated)', 'main,develop,master');
+    const commitPrefixesStr = await question(rl, 'Commit prefixes (comma-separated)', 'feat,fix,chore');
+    rules = {
+      allowedBranches: parseList(allowedBranchesStr),
+      commitPrefixes: parseList(commitPrefixesStr),
+    };
+    ai = {
+      provider: aiProvider.toLowerCase(),
+      model: DEFAULT_MODELS[aiProvider.toLowerCase()] || DEFAULT_MODELS.groq,
+    };
+  }
+
+  let config;
+  if (target === 'jira') config = await askJiraConfig(rl, ai, rules);
+  else if (target === 'trello') config = quick ? await askTrelloConfigQuick(rl, ai, rules) : await askTrelloConfig(rl, ai, rules);
+  else config = await askLinearConfig(rl, ai, rules);
+
+  return { target, config };
+}
+
 export async function runInit(options = {}) {
   const quick = options.quick === true;
+  const presetTarget = normalizePresetTarget(options.preset);
+  const usePreset = presetTarget && presetTarget !== '__invalid__';
   const cwd = process.cwd();
   const rcPath = resolve(cwd, '.haitaskrc');
 
@@ -147,38 +219,33 @@ export async function runInit(options = {}) {
     return;
   }
 
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-
-  try {
-    console.log(quick ? 'haitask init --quick (minimal questions, defaults for the rest).\n' : 'haitask init — answer the questions (Enter = use default).\n');
+  if (presetTarget === '__invalid__') {
+    console.error(`Invalid preset target "${options.preset}". Use one of: ${VALID_TARGETS.join(', ')}.`);
+    process.exitCode = 1;
+    return;
+  }
 
-    const targetAnswer = await question(rl, 'Target: 1 = Jira, 2 = Trello, 3 = Linear', '1');
-    const targetMap = { '1': 'jira', '2': 'trello', '3': 'linear' };
-    const target = targetMap[targetAnswer] || 'jira';
+  if (usePreset) {
+    const config = buildPresetConfig(presetTarget);
+    writeFileSync(rcPath, JSON.stringify(config, null, 2), 'utf-8');
+    console.log(`Created .haitaskrc from preset: ${presetTarget}`);
+    writeEnvFile(cwd, presetTarget, '1');
 
-    let rules;
-    let ai;
-    if (quick) {
-      rules = DEFAULT_RULES;
-      ai = DEFAULT_AI;
-    } else {
-      const aiProvider = await question(rl, 'AI provider (groq | deepseek | openai)', 'groq');
-      const allowedBranchesStr = await question(rl, 'Allowed branches (comma-separated)', 'main,develop,master');
-      const commitPrefixesStr = await question(rl, 'Commit prefixes (comma-separated)', 'feat,fix,chore');
-      rules = {
-        allowedBranches: parseList(allowedBranchesStr),
-        commitPrefixes: parseList(commitPrefixesStr),
-      };
-      ai = {
-        provider: aiProvider.toLowerCase(),
-        model: DEFAULT_MODELS[aiProvider.toLowerCase()] || DEFAULT_MODELS.groq,
-      };
+    const { valid, missing } = validateEnv(cwd, config);
+    if (!valid) {
+      printEnvHints(config, missing);
+      process.exitCode = 1;
+      return;
     }
+    console.log('\nEnvironment looks good. Run "haitask run" after your next commit.');
+    return;
+  }
 
-    let config;
-    if (target === 'jira') config = await askJiraConfig(rl, ai, rules);
-    else if (target === 'trello') config = quick ? await askTrelloConfigQuick(rl, ai, rules) : await askTrelloConfig(rl, ai, rules);
-    else config = await askLinearConfig(rl, ai, rules);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    console.log(quick ? 'haitask init --quick (minimal questions, defaults for the rest).\n' : 'haitask init — answer the questions (Enter = use default).\n');
+    const { target, config } = await buildInteractiveConfig(rl, quick);
 
     writeFileSync(rcPath, JSON.stringify(config, null, 2), 'utf-8');
     console.log('\nCreated .haitaskrc');

package/src/commands/run.js

@@ -13,18 +13,87 @@ function getDisplayUrl(config, key, resultUrl) {
   return target === 'jira' ? buildJiraUrl(config, key) : key;
 }
 
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function printFailure(json, message, prefix = null) {
+  if (json) {
+    printJson({ ok: false, error: prefix ? `${prefix}: ${message}` : message });
+  } else if (prefix) {
+    console.error(`${prefix}:`, message);
+  } else {
+    console.error(message);
+  }
+  process.exitCode = 1;
+}
+
+function toJsonResult(result, config) {
+  const displayUrl = getDisplayUrl(config, result.key, result.url);
+  return {
+    ok: true,
+    dry: !!result.dry,
+    skipped: !!result.skipped,
+    commented: !!result.commented,
+    key: result.key || null,
+    url: displayUrl || null,
+    payload: result.payload || null,
+    commit: result.commitData
+      ? {
+          branch: result.commitData.branch,
+          commitHash: result.commitData.commitHash,
+          repoName: result.commitData.repoName,
+          count: result.commitData.count || 1,
+        }
+      : null,
+  };
+}
+
+function printDryResult(result) {
+  console.log('Dry run — no task created.');
+  if (result.commented) {
+    console.log('Would add comment to existing:', result.key);
+    return;
+  }
+  const msg = result.commitData?.message || '';
+  const preview = msg.includes('\n\n---\n\n') ? `${result.commitData?.count ?? '?'} commits` : msg.split('\n')[0] || '';
+  console.log('Commit(s):', preview);
+  console.log('Would create task:', result.payload?.title || '');
+  if (result.payload?.description) {
+    const desc = result.payload.description;
+    console.log('Description (preview):', desc.slice(0, 120) + (desc.length > 120 ? '...' : ''));
+  }
+}
+
+function printSuccessResult(result, config) {
+  if (result.dry) {
+    printDryResult(result);
+    return;
+  }
+
+  const displayUrl = getDisplayUrl(config, result.key, result.url);
+  if (result.skipped) {
+    console.log('Already created for this commit:', result.key);
+  } else if (result.commented) {
+    console.log('Added comment to:', result.key);
+  } else {
+    console.log('Created task:', result.key);
+  }
+  if (displayUrl && displayUrl !== result.key) console.log(displayUrl);
+}
+
 export async function runRun(options = {}) {
   const dry = options.dry ?? false;
+  const json = options.json ?? false;
   const type = options.type?.trim() || undefined;
   const status = options.status?.trim() || undefined;
-  const commits = options.commits != null ? Number(options.commits) : 1;
+  const commits = Number(options.commits ?? 1);
 
   let config;
   try {
     config = loadConfig();
   } catch (err) {
-    console.error('Config error:', err.message);
-    process.exitCode = 1;
+    printFailure(json, err.message, 'Config error');
     return;
   }
 
@@ -32,37 +101,16 @@ export async function runRun(options = {}) {
     const result = await runPipeline(config, { dry, issueType: type, transitionToStatus: status, commits });
 
     if (!result.ok) {
-      console.error(result.error || 'Pipeline failed.');
-      process.exitCode = 1;
+      printFailure(json, result.error || 'Pipeline failed.');
       return;
     }
 
-    if (result.dry) {
-      console.log('Dry run — no task created.');
-      if (result.commented) {
-        console.log('Would add comment to existing:', result.key);
-      } else {
-        const msg = result.commitData?.message || '';
-        const preview = msg.includes('\n\n---\n\n') ? `${result.commitData?.count ?? '?'} commits` : msg.split('\n')[0] || '';
-        console.log('Commit(s):', preview);
-        console.log('Would create task:', result.payload?.title || '');
-        if (result.payload?.description) {
-          const desc = result.payload.description;
-          console.log('Description (preview):', desc.slice(0, 120) + (desc.length > 120 ? '...' : ''));
-        }
-      }
+    if (json) {
+      printJson(toJsonResult(result, config));
       return;
     }
-
-    const displayUrl = getDisplayUrl(config, result.key, result.url);
-    if (result.commented) {
-      console.log('Added comment to:', result.key);
-    } else {
-      console.log('Created task:', result.key);
-    }
-    if (displayUrl && displayUrl !== result.key) console.log(displayUrl);
+    printSuccessResult(result, config);
   } catch (err) {
-    console.error('Error:', err.message);
-    process.exitCode = 1;
+    printFailure(json, err.message, 'Error');
   }
 }

package/src/core/pipeline.js

@@ -2,12 +2,14 @@
  * Pipeline: Git → AI → target (Jira, Trello, …).
  * Orchestrates steps. No direct I/O (no console.log).
  * Returns structured result for CLI to display.
+ * Idempotency: same commit hash → skip create, return stored key/url.
  */
 
 import { getLatestCommitData, getLatestCommitsData } from '../git/commit.js';
 import { generateTaskPayload } from '../ai/index.js';
 import { createTask, addComment } from '../backend/index.js';
 import { extractIssueKey } from '../utils/issue-key.js';
+import { readState, writeState } from '../utils/idempotency.js';
 
 const BATCH_SEP = '\n\n---\n\n';
 
@@ -75,12 +77,22 @@ export async function runPipeline(config, options = {}) {
     return { ok: true, dry: true, payload, commitData };
   }
 
+  const commitHash = commitData.commitHash;
+  const repoRoot = commitData.repoRoot;
+  const state = repoRoot && commitHash ? readState(repoRoot) : null;
+  if (state?.commitHash === commitHash && state?.taskKey) {
+    return { ok: true, skipped: true, key: state.taskKey, url: state.taskUrl, payload, commitData };
+  }
+
   const mergedConfig =
     target === 'jira'
       ? mergeJiraOverrides(config, { issueType: typeOverride, transitionToStatus: statusOverride })
       : config;
 
   const { key, url } = await createTask(payload, mergedConfig);
+  if (repoRoot && commitHash && key) {
+    writeState(repoRoot, { commitHash, taskKey: key, taskUrl: url });
+  }
   return { ok: true, key, url, payload, commitData };
 }
 

package/src/git/commit.js

@@ -10,8 +10,8 @@ const CWD = process.cwd();
 const BATCH_SEP = '\n\n---\n\n';
 
 /**
- * Get latest commit message, current branch, and repo (root folder) name.
- * @returns {Promise<{ message: string, branch: string, repoName: string }>}
+ * Get latest commit message, current branch, repo root, and commit hash (HEAD).
+ * @returns {Promise<{ message: string, branch: string, repoName: string, repoRoot: string, commitHash: string }>}
  * @throws {Error} If not a git repo or git command fails
  */
 export async function getLatestCommitData() {
@@ -19,24 +19,26 @@ export async function getLatestCommitData() {
 }
 
 /**
- * Get last N commit messages combined, current branch, and repo name.
+ * Get last N commit messages combined, current branch, repo name/root, and latest commit hash (HEAD).
  * @param {number} n - Number of commits (>= 1)
- * @returns {Promise<{ message: string, branch: string, repoName: string, count: number }>}
+ * @returns {Promise<{ message: string, branch: string, repoName: string, repoRoot: string, commitHash: string, count: number }>}
  */
 export async function getLatestCommitsData(n = 1) {
   const num = Math.max(1, Number(n) || 1);
-  const [logResult, branchResult, rootResult] = await Promise.all([
+  const [logResult, branchResult, rootResult, hashResult] = await Promise.all([
     execa('git', ['log', `-${num}`, '--pretty=format:%B%x00'], { cwd: CWD }),
     execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: CWD }),
     execa('git', ['rev-parse', '--show-toplevel'], { cwd: CWD }),
+    execa('git', ['rev-parse', 'HEAD'], { cwd: CWD }),
   ]);
 
   const raw = logResult.stdout || '';
   const branch = (branchResult.stdout || '').trim();
   const repoRoot = (rootResult.stdout || '').trim();
   const repoName = repoRoot ? basename(repoRoot) : '';
+  const commitHash = (hashResult.stdout || '').trim();
 
   const parts = raw.split('\0').map((s) => s.trim()).filter(Boolean).slice(0, num);
   const message = parts.length > 1 ? parts.join(BATCH_SEP) : (parts[0] || raw.trim());
-  return { message, branch, repoName, count: parts.length };
+  return { message, branch, repoName, repoRoot, commitHash, count: parts.length };
 }

package/src/index.js

@@ -5,6 +5,7 @@ import { loadEnvFiles } from './config/env-loader.js';
 import { program } from 'commander';
 import { runInit } from './commands/init.js';
 import { runRun } from './commands/run.js';
+import { runCheck } from './commands/check.js';
 
 loadEnvFiles();
 
@@ -20,12 +21,19 @@ program
   .command('init')
   .description('Create .haitaskrc and validate environment')
   .option('--quick', 'Use defaults (target + minimal questions); one Enter for Jira/Trello/Linear choice')
+  .option('--preset <target>', 'Preset target without target prompt (jira|trello|linear)')
   .action((opts) => runInit(opts));
 
+program
+  .command('check')
+  .description('Validate .haitaskrc and required env without running pipeline')
+  .action(() => runCheck());
+
 program
   .command('run')
   .description('Run full pipeline: Git → AI → target (Jira, Trello, or Linear)')
   .option('--dry', 'Skip creating task, run everything else')
+  .option('--json', 'Print machine-readable JSON output')
   .option('-c, --commits <n>', 'Number of commits to combine into one task (default: 1)', '1')
   .option('-t, --type <type>', 'Jira issue type for this run (e.g. Task, Bug, Story). Overrides .haitaskrc jira.issueType')
   .option('-s, --status <status>', 'Jira transition-to status after create (e.g. Done, "To Do"). Overrides .haitaskrc jira.transitionToStatus')

package/src/jira/client.js

@@ -3,6 +3,8 @@
  * Jira Cloud REST API v3.
  */
 
+import { getHttpHint } from '../utils/http-hints.js';
+
 const ASSIGN_DELAY_MS = 4000;
 const DEFAULT_PROJECT_KEY = 'PROJ';
 const DEFAULT_ISSUE_TYPE = 'Task';
@@ -207,7 +209,11 @@ export async function createIssue(payload, config) {
     }
     if (!createRes.ok) {
       const errText = createRes.bodyUsed ? firstErrorText : await createRes.text();
-      throw new Error(`Jira API error ${createRes.status}: ${errText || createRes.statusText}`);
+      const hint = getHttpHint('jira', createRes.status);
+      const msg = `Jira API error ${createRes.status}: ${errText || createRes.statusText}${hint ? ' ' + hint : ''}`;
+      const err = new Error(msg);
+      err.status = createRes.status;
+      throw err;
     }
   }
 
@@ -250,7 +256,10 @@ export async function addComment(issueKey, bodyText, config) {
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Jira comment API ${res.status}: ${text || res.statusText}`);
+    const hint = getHttpHint('jira', res.status);
+    const err = new Error(`Jira comment API ${res.status}: ${text || res.statusText}${hint ? ' ' + hint : ''}`);
+    err.status = res.status;
+    throw err;
   }
   const url = `${baseUrl}/browse/${issueKey}`;
   return { key: issueKey, url };

package/src/linear/client.js

@@ -3,6 +3,8 @@
  * API: https://api.linear.app/graphql
  */
 
+import { getHttpHint } from '../utils/http-hints.js';
+
 const LINEAR_GRAPHQL = 'https://api.linear.app/graphql';
 
 const CREATE_ISSUE_MUTATION = `
@@ -13,6 +15,59 @@ const CREATE_ISSUE_MUTATION = `
   }
 `;
 
+const TEAM_LABELS_QUERY = `
+  query TeamLabels($teamId: String!) {
+    team(id: $teamId) {
+      labels {
+        nodes { id name }
+      }
+    }
+  }
+`;
+
+function toLinearPriority(priority) {
+  const p = (priority || '').trim();
+  if (p === 'Highest') return 1;
+  if (p === 'High') return 2;
+  if (p === 'Low' || p === 'Lowest') return 4;
+  return 3;
+}
+
+async function resolveLinearLabelIds(apiKey, teamId, labels) {
+  const desired = (Array.isArray(labels) ? labels : [])
+    .filter((v) => typeof v === 'string' && v.trim())
+    .map((v) => v.trim().toLowerCase());
+  if (desired.length === 0) return [];
+
+  try {
+    const res = await fetch(LINEAR_GRAPHQL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        Authorization: apiKey,
+      },
+      body: JSON.stringify({
+        query: TEAM_LABELS_QUERY,
+        variables: { teamId },
+      }),
+    });
+    if (!res.ok) return [];
+    const data = await res.json();
+    const nodes = data?.data?.team?.labels?.nodes;
+    if (!Array.isArray(nodes)) return [];
+
+    const byName = new Map();
+    for (const node of nodes) {
+      const key = typeof node?.name === 'string' ? node.name.trim().toLowerCase() : '';
+      if (key && typeof node?.id === 'string') byName.set(key, node.id);
+    }
+    return desired.map((name) => byName.get(name)).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Create a Linear issue from AI payload. Same interface as Jira/Trello: returns { key, url }.
  * @param {object} payload - { title, description, labels, priority } from AI
@@ -35,6 +90,8 @@ export async function createTask(payload, config) {
 
   const title = (payload?.title || '').trim() || 'Untitled';
   const description = (payload?.description || '').trim() || '';
+  const priority = toLinearPriority(payload?.priority);
+  const labelIds = await resolveLinearLabelIds(apiKey, teamId, payload?.labels);
 
   const res = await fetch(LINEAR_GRAPHQL, {
     method: 'POST',
@@ -50,6 +107,8 @@ export async function createTask(payload, config) {
           teamId,
           title,
           ...(description && { description }),
+          ...(Number.isFinite(priority) && { priority }),
+          ...(labelIds.length > 0 && { labelIds }),
         },
       },
     }),
@@ -57,7 +116,10 @@ export async function createTask(payload, config) {
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Linear API error ${res.status}: ${text || res.statusText}`);
+    const hint = getHttpHint('linear', res.status);
+    const err = new Error(`Linear API error ${res.status}: ${text || res.statusText}${hint ? ' ' + hint : ''}`);
+    err.status = res.status;
+    throw err;
   }
 
   const data = await res.json();
@@ -108,7 +170,13 @@ export async function addComment(identifier, bodyText, config) {
     headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: apiKey },
     body: JSON.stringify({ query: GET_ISSUE_QUERY, variables: { identifier: id } }),
   });
-  if (!resIssue.ok) throw new Error(`Linear API ${resIssue.status}: ${await resIssue.text()}`);
+  if (!resIssue.ok) {
+    const text = await resIssue.text();
+    const hint = getHttpHint('linear', resIssue.status);
+    const e = new Error(`Linear API ${resIssue.status}: ${text}${hint ? ' ' + hint : ''}`);
+    e.status = resIssue.status;
+    throw e;
+  }
   const dataIssue = await resIssue.json();
   const issue = dataIssue?.data?.issue;
   if (!issue?.id) {
@@ -124,7 +192,13 @@ export async function addComment(identifier, bodyText, config) {
       variables: { input: { issueId: issue.id, body: (bodyText || '').trim() || '(no message)' } },
     }),
   });
-  if (!resComment.ok) throw new Error(`Linear comment API ${resComment.status}: ${await resComment.text()}`);
+  if (!resComment.ok) {
+    const text = await resComment.text();
+    const hint = getHttpHint('linear', resComment.status);
+    const e = new Error(`Linear comment API ${resComment.status}: ${text}${hint ? ' ' + hint : ''}`);
+    e.status = resComment.status;
+    throw e;
+  }
   const dataComment = await resComment.json();
   if (dataComment?.errors?.[0]) throw new Error(`Linear comment: ${dataComment.errors[0].message}`);
 

package/src/trello/client.js

@@ -4,9 +4,54 @@
  */
 
 import { TRELLO_ID_REGEX } from '../config/constants.js';
+import { getHttpHint } from '../utils/http-hints.js';
 
 const TRELLO_API = 'https://api.trello.com/1';
 
+function withPriorityInDescription(description, priority) {
+  const p = (priority || '').trim();
+  if (!p) return description;
+  return `Priority: ${p}\n\n${description}`.trim();
+}
+
+async function resolveTrelloLabelIds(apiKey, token, listId, labels) {
+  const desired = (Array.isArray(labels) ? labels : [])
+    .filter((v) => typeof v === 'string' && v.trim())
+    .map((v) => v.trim().toLowerCase());
+  if (desired.length === 0) return [];
+
+  try {
+    const query = new URLSearchParams({ key: apiKey, token });
+    const listRes = await fetch(`${TRELLO_API}/lists/${encodeURIComponent(listId)}?fields=idBoard&${query.toString()}`, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+    });
+    if (!listRes.ok) return [];
+    const listData = await listRes.json();
+    const boardId = listData?.idBoard;
+    if (!boardId || !TRELLO_ID_REGEX.test(boardId)) return [];
+
+    const labelsRes = await fetch(
+      `${TRELLO_API}/boards/${encodeURIComponent(boardId)}/labels?fields=id,name&limit=1000&${query.toString()}`,
+      { method: 'GET', headers: { Accept: 'application/json' } }
+    );
+    if (!labelsRes.ok) return [];
+    const boardLabels = await labelsRes.json();
+    if (!Array.isArray(boardLabels)) return [];
+
+    const byName = new Map();
+    for (const label of boardLabels) {
+      const name = typeof label?.name === 'string' ? label.name.trim().toLowerCase() : '';
+      if (name && typeof label?.id === 'string' && TRELLO_ID_REGEX.test(label.id)) {
+        byName.set(name, label.id);
+      }
+    }
+    return desired.map((name) => byName.get(name)).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Create a Trello card from AI payload. Same interface as Jira adapter: returns { key, url }.
  * @param {object} payload - { title, description, labels, priority } from AI
@@ -35,7 +80,7 @@ export async function createTask(payload, config) {
   }
 
   const name = (payload?.title || '').trim() || 'Untitled';
-  const desc = (payload?.description || '').trim() || '';
+  const desc = withPriorityInDescription((payload?.description || '').trim() || '', payload?.priority);
 
   const query = new URLSearchParams({ key: apiKey, token });
   const body = { idList: listId, name, desc };
@@ -44,12 +89,16 @@ export async function createTask(payload, config) {
   const memberId = trello.memberId?.trim() || process.env.TRELLO_MEMBER_ID?.trim();
   if (memberId && TRELLO_ID_REGEX.test(memberId)) body.idMembers = [memberId];
 
-  const labelIds = trello.labelIds;
-  if (Array.isArray(labelIds) && labelIds.length > 0) {
-    body.idLabels = labelIds
+  const configLabelIds = Array.isArray(trello.labelIds)
+    ? trello.labelIds
       .filter((id) => typeof id === 'string' && id.trim())
       .map((id) => id.trim())
-      .filter((id) => TRELLO_ID_REGEX.test(id));
+      .filter((id) => TRELLO_ID_REGEX.test(id))
+    : [];
+  const aiLabelIds = await resolveTrelloLabelIds(apiKey, token, listId, payload?.labels);
+  const mergedLabelIds = [...new Set([...configLabelIds, ...aiLabelIds])];
+  if (mergedLabelIds.length > 0) {
+    body.idLabels = mergedLabelIds;
   }
 
   const url = `${TRELLO_API}/cards?${query.toString()}`;
@@ -61,7 +110,10 @@ export async function createTask(payload, config) {
 
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Trello API error ${res.status}: ${text || res.statusText}`);
+    const hint = getHttpHint('trello', res.status);
+    const err = new Error(`Trello API error ${res.status}: ${text || res.statusText}${hint ? ' ' + hint : ''}`);
+    err.status = res.status;
+    throw err;
   }
 
   const card = await res.json();
@@ -95,7 +147,10 @@ export async function addComment(cardIdOrShortLink, bodyText, config) {
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Trello comment API ${res.status}: ${text || res.statusText}`);
+    const hint = getHttpHint('trello', res.status);
+    const err = new Error(`Trello comment API ${res.status}: ${text || res.statusText}${hint ? ' ' + hint : ''}`);
+    err.status = res.status;
+    throw err;
   }
   return { key: id, url: `https://trello.com/c/${id}` };
 }

package/src/utils/http-hints.js

@@ -0,0 +1,34 @@
+/**
+ * Short hints for API errors (401, 403, 404) to help users fix config.
+ */
+
+const HINTS = {
+  jira: {
+    401: 'Check JIRA_EMAIL and JIRA_API_TOKEN in .env.',
+    403: 'Check project permissions and that the user is an assignable user.',
+    404: 'Check JIRA_BASE_URL and jira.projectKey in .haitaskrc.',
+  },
+  trello: {
+    401: 'Check TRELLO_API_KEY and TRELLO_TOKEN in .env. Get them at https://trello.com/app-key',
+    403: 'Check board and list access (token may not have write permission).',
+    404: 'Check trello.listId (list where cards go) or the card ID.',
+  },
+  linear: {
+    401: 'Check LINEAR_API_KEY in .env. Get a key at https://linear.app/settings/api',
+    403: 'Check team permissions and API key scope.',
+    404: 'Check linear.teamId in .haitaskrc or the issue identifier.',
+  },
+};
+
+/**
+ * @param {string} target - 'jira' | 'trello' | 'linear'
+ * @param {number} status - HTTP status
+ * @returns {string} Hint to append to error message, or ''
+ */
+export function getHttpHint(target, status) {
+  const s = Number(status);
+  if (!s || s < 400) return '';
+  const map = HINTS[target];
+  if (!map) return '';
+  return map[s] || '';
+}

package/src/utils/idempotency.js

@@ -0,0 +1,46 @@
+/**
+ * Idempotency: remember last created task per commit hash so we don't create duplicates.
+ * State file: .git/haitask-state.json (inside repo, not committed).
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STATE_FILENAME = 'haitask-state.json';
+
+function statePath(repoRoot) {
+  return join(repoRoot || '', '.git', STATE_FILENAME);
+}
+
+/**
+ * Read last stored result for idempotency check.
+ * @param {string} repoRoot - Git repo root path (e.g. from git rev-parse --show-toplevel)
+ * @returns {{ commitHash?: string, taskKey?: string, taskUrl?: string } | null}
+ */
+export function readState(repoRoot) {
+  if (!repoRoot?.trim()) return null;
+  const path = statePath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const data = JSON.parse(raw);
+    return data && typeof data === 'object' ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write state after successfully creating a task (so next run with same commit skips).
+ * @param {string} repoRoot - Git repo root path
+ * @param {{ commitHash: string, taskKey: string, taskUrl?: string }} state
+ */
+export function writeState(repoRoot, state) {
+  if (!repoRoot?.trim() || !state?.commitHash || !state?.taskKey) return;
+  const path = statePath(repoRoot);
+  try {
+    writeFileSync(path, JSON.stringify(state, null, 0), 'utf-8');
+  } catch {
+    // ignore write errors (e.g. read-only .git)
+  }
+}

package/src/utils/retry.js

@@ -0,0 +1,50 @@
+/**
+ * Retry a promise-returning function on retryable failures (5xx, 429, network).
+ * Non-retryable: 4xx (except 429). Errors with .status are treated as HTTP status.
+ */
+
+const DEFAULT_RETRIES = 2;
+const DEFAULT_DELAY_MS = 1000;
+const DEFAULT_BACKOFF = 2;
+
+function isRetryable(err) {
+  if (!err) return false;
+  const status = err.status;
+  if (status != null) {
+    if (status === 429) return true; // rate limit
+    if (status >= 500 && status < 600) return true; // server error
+    return false; // 4xx (except 429) — don't retry
+  }
+  // Network / timeout / DNS
+  if (err instanceof TypeError && err.message?.includes?.('fetch')) return true;
+  if (err.code === 'ECONNRESET' || err.code === 'ETIMEDOUT' || err.code === 'ENOTFOUND') return true;
+  return false;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Call fn(); on reject, retry up to retries times if error is retryable (5xx, 429, network).
+ * @param {() => Promise<T>} fn
+ * @param {{ retries?: number, delayMs?: number, backoff?: number }} options
+ * @returns {Promise<T>}
+ */
+export async function withRetry(fn, options = {}) {
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  let delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
+  const backoff = options.backoff ?? DEFAULT_BACKOFF;
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt === retries || !isRetryable(err)) throw err;
+      await sleep(delayMs);
+      delayMs *= backoff;
+    }
+  }
+  throw lastError;
+}