haitask 0.3.1 → 0.3.3

package/README.md

@@ -62,6 +62,7 @@ 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 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 --commits N` | Combine the last N commits into one task (e.g. `--commits 3`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haitask",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "HAITASK — 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",
@@ -44,4 +44,4 @@
     "dotenv": "^16.4.5",
     "execa": "^9.5.2"
   }
-}
+}

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/run.js

@@ -55,7 +55,9 @@ export async function runRun(options = {}) {
     }
 
     const displayUrl = getDisplayUrl(config, result.key, result.url);
-    if (result.commented) {
+    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);

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();
 
@@ -22,6 +23,11 @@ program
   .option('--quick', 'Use defaults (target + minimal questions); one Enter for Jira/Trello/Linear choice')
   .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)')

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 = `
@@ -57,7 +59,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 +113,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 +135,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,6 +4,7 @@
  */
 
 import { TRELLO_ID_REGEX } from '../config/constants.js';
+import { getHttpHint } from '../utils/http-hints.js';
 
 const TRELLO_API = 'https://api.trello.com/1';
 
@@ -61,7 +62,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 +99,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;
+}