@relipa/ai-flow-kit 0.1.9 → 0.2.0-beta.1

package/scripts/ticket-writer.js

@@ -0,0 +1,247 @@
+'use strict';
+// Vấn đề 5 (docs/internal/PM Workflow_v1.0.md) — turns an AI-proposed, PM-approved task list
+// (born out of `ingest-data` Gate 3) into real tickets on Backlog/Jira.
+//
+// Read access (fetch-links, listing projects/issueTypes/priorities) reuses the existing
+// read-only credentials already configured for `ak use`/`ak fetch-links`. Creating a ticket is a
+// WRITE action and requires a SEPARATE credential (`BACKLOG_API_KEY_WRITE` / `JIRA_API_TOKEN_WRITE`)
+// — same "distinct WRITE key" policy the PM Workflow doc calls for, kept apart from the read key so
+// a compromised/misconfigured read key can never create tickets.
+
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const useCommand = require('./use');
+const linkResolver = require('./link-resolver');
+
+const {
+  loadCredentials,
+  resolveBacklogCredentials,
+  resolveJiraCredentials,
+  saveMcpCredentials,
+} = useCommand;
+
+const {
+  fetchBacklogIssueTypes,
+  fetchBacklogPriorities,
+  createBacklogIssue,
+  createJiraIssue,
+} = linkResolver;
+
+// Only these keys can be written via `ak credentials set` — dedicated adapter credentials
+// (BACKLOG_API_KEY, JIRA_API_TOKEN, ...) still go through `ak init --adapter` on purpose.
+const SETTABLE_CREDENTIAL_KEYS = [
+  'BACKLOG_API_KEY_WRITE',
+  'JIRA_API_TOKEN_WRITE',
+  'JIRA_EMAIL_WRITE',
+  'BACKLOG_DEFAULT_PROJECT_ID',
+  'BACKLOG_DEFAULT_PROJECT_KEY',
+  'JIRA_DEFAULT_PROJECT_KEY',
+];
+
+function jiraFullDomain(domain) {
+  return domain.includes('.') ? domain : `${domain}.atlassian.net`;
+}
+
+function missingCredResult(target, field, message) {
+  return { ok: false, error: 'missing-write-credentials', target, field, message };
+}
+
+async function resolveBacklogWrite(creds) {
+  const read = resolveBacklogCredentials(creds);
+  if (!read) {
+    return missingCredResult(
+      'backlog', 'BACKLOG_API_KEY / BACKLOG_SPACE_KEY',
+      'Chưa cấu hình credentials đọc Backlog. Chạy `ak init --adapter backlog` trước.'
+    );
+  }
+  const apiKeyWrite = process.env.BACKLOG_API_KEY_WRITE || creds.BACKLOG_API_KEY_WRITE;
+  if (!apiKeyWrite) {
+    return missingCredResult(
+      'backlog', 'BACKLOG_API_KEY_WRITE',
+      'Cần API key Backlog có quyền tạo issue (khác key đọc hiện tại). Cung cấp API key này, mình sẽ lưu lại và tạo ticket ngay.'
+    );
+  }
+  return { ok: true, domain: read.domain, apiKeyRead: read.apiKey, apiKeyWrite };
+}
+
+async function resolveJiraWrite(creds) {
+  const read = resolveJiraCredentials(creds);
+  if (!read) {
+    return missingCredResult(
+      'jira', 'JIRA_API_TOKEN / JIRA_EMAIL / JIRA_DOMAIN',
+      'Chưa cấu hình credentials đọc Jira. Chạy `ak init --adapter jira` trước.'
+    );
+  }
+  const apiTokenWrite = process.env.JIRA_API_TOKEN_WRITE || creds.JIRA_API_TOKEN_WRITE;
+  if (!apiTokenWrite) {
+    return missingCredResult(
+      'jira', 'JIRA_API_TOKEN_WRITE',
+      'Cần Jira API token có quyền tạo issue (khác token đọc hiện tại). Cung cấp token này, mình sẽ lưu lại và tạo ticket ngay.'
+    );
+  }
+  const emailWrite = process.env.JIRA_EMAIL_WRITE || creds.JIRA_EMAIL_WRITE || read.email;
+  return { ok: true, domain: jiraFullDomain(read.domain), emailWrite, apiTokenWrite };
+}
+
+async function pickBacklogDefaults(domain, apiKeyRead, projectId) {
+  const [issueTypes, priorities] = await Promise.all([
+    fetchBacklogIssueTypes(domain, apiKeyRead, projectId),
+    fetchBacklogPriorities(domain, apiKeyRead),
+  ]);
+  if (!issueTypes || !issueTypes.length) throw new Error(`Project ${projectId} không có issueType nào — không thể tạo issue.`);
+  const defaultIssueTypeId = issueTypes[0].id;
+  const normal = (priorities || []).find((p) => /normal|trung bình/i.test(p.name));
+  const defaultPriorityId = (normal || (priorities || [])[0] || {}).id;
+  if (!defaultPriorityId) throw new Error('Không lấy được danh sách priority từ Backlog.');
+  return { defaultIssueTypeId, defaultPriorityId };
+}
+
+/**
+ * `ak tasks create-tickets <file.json> [--json]`
+ *
+ * Input file shape:
+ * {
+ *   "target": "backlog" | "jira",
+ *   "projectId": "12345",     // optional — Backlog only, overrides BACKLOG_DEFAULT_PROJECT_ID
+ *   "projectKey": "PROJ",     // optional — Jira only, overrides JIRA_DEFAULT_PROJECT_KEY
+ *   "tasks": [
+ *     { "type": "spec|coding|test|other", "title": "...", "description": "..." }
+ *   ]
+ * }
+ *
+ * `description` is expected to already be fully composed by the AI per the ticket template in
+ * PM Workflow_v1.0.md §6.1 (Nội dung task + Nguồn tham chiếu) — this command posts it as-is.
+ */
+async function createTicketsCommand(inputFile, options = {}) {
+  const emit = (obj) => {
+    if (options.json) { process.stdout.write(JSON.stringify(obj)); return; }
+    if (obj.ok === false) {
+      console.log(chalk.red(`✗ ${obj.message || obj.error}`));
+    } else {
+      console.log(chalk.green(`✓ ${obj.results.filter(r => r.ok).length}/${obj.results.length} ticket(s) created on ${obj.target}.`));
+      for (const r of obj.results) {
+        console.log(r.ok ? `  ${chalk.green('✓')} ${r.ticketId}  ${chalk.gray(r.title)}` : `  ${chalk.red('✗')} ${chalk.gray(r.title)} — ${r.error}`);
+      }
+    }
+    console.log(JSON.stringify(obj));
+  };
+
+  let input;
+  try {
+    input = await fs.readJson(inputFile);
+  } catch (err) {
+    emit({ ok: false, error: 'invalid-input-file', message: `Không đọc được ${inputFile}: ${err.message}` });
+    process.exitCode = 1;
+    return;
+  }
+
+  const target = input.target;
+  const tasks = input.tasks || [];
+  if (!['backlog', 'jira'].includes(target)) {
+    emit({ ok: false, error: 'invalid-target', message: `target phải là "backlog" hoặc "jira", nhận được: ${target}` });
+    process.exitCode = 1;
+    return;
+  }
+  if (!tasks.length) {
+    emit({ ok: false, error: 'empty-tasks', message: 'File input không có task nào trong "tasks".' });
+    process.exitCode = 1;
+    return;
+  }
+
+  const creds = await loadCredentials();
+
+  if (target === 'backlog') {
+    const write = await resolveBacklogWrite(creds);
+    if (!write.ok) { emit(write); process.exitCode = 2; return; }
+
+    const projectId = input.projectId || creds.BACKLOG_DEFAULT_PROJECT_ID;
+    if (!projectId) {
+      emit({
+        ok: false, error: 'missing-project',
+        message: 'Chưa xác định projectId đích trên Backlog. Chạy `ak backlog-projects` để xem danh sách, rồi `ak backlog-set-default-project <id> <key>`.',
+      });
+      process.exitCode = 2;
+      return;
+    }
+
+    let defaults;
+    try {
+      defaults = await pickBacklogDefaults(write.domain, write.apiKeyRead, projectId);
+    } catch (err) {
+      emit({ ok: false, error: 'project-lookup-failed', message: err.message });
+      process.exitCode = 1;
+      return;
+    }
+
+    const results = [];
+    for (const task of tasks) {
+      try {
+        const created = await createBacklogIssue(write.domain, write.apiKeyWrite, {
+          projectId,
+          summary: task.title,
+          description: task.description,
+          issueTypeId: task.issueTypeId || defaults.defaultIssueTypeId,
+          priorityId: task.priorityId || defaults.defaultPriorityId,
+        });
+        results.push({ type: task.type, title: task.title, ok: true, ticketId: created.ticketId, url: created.url });
+      } catch (err) {
+        results.push({ type: task.type, title: task.title, ok: false, error: err.message });
+      }
+    }
+    emit({ ok: true, target, projectId, results });
+    return;
+  }
+
+  // target === 'jira'
+  const write = await resolveJiraWrite(creds);
+  if (!write.ok) { emit(write); process.exitCode = 2; return; }
+
+  const projectKey = input.projectKey || creds.JIRA_DEFAULT_PROJECT_KEY;
+  if (!projectKey) {
+    emit({
+      ok: false, error: 'missing-project',
+      message: 'Chưa xác định project đích trên Jira. Chạy `ak jira-projects` để xem danh sách, rồi `ak jira-set-default-project <key>`.',
+    });
+    process.exitCode = 2;
+    return;
+  }
+
+  const results = [];
+  for (const task of tasks) {
+    try {
+      const created = await createJiraIssue(write.domain, write.emailWrite, write.apiTokenWrite, {
+        projectKey,
+        summary: task.title,
+        description: task.description,
+        issueTypeName: task.issueType || 'Task',
+      });
+      results.push({ type: task.type, title: task.title, ok: true, ticketId: created.ticketId, url: created.url });
+    } catch (err) {
+      results.push({ type: task.type, title: task.title, ok: false, error: err.message });
+    }
+  }
+  emit({ ok: true, target, projectKey, results });
+}
+
+/**
+ * `ak credentials set <KEY> <VALUE>` — lets the AI persist a WRITE key the user pasted in chat
+ * (after being asked, per the missing-write-credentials error above) without a bespoke command
+ * per key. Restricted to an allowlist — dedicated adapter read-credentials still go through
+ * `ak init --adapter`, this is only for the pieces that flow introduced.
+ */
+async function setCredentialCommand(key, value) {
+  if (!SETTABLE_CREDENTIAL_KEYS.includes(key)) {
+    console.log(chalk.red(`✗ Unknown credential key: ${key}.`));
+    console.log(chalk.gray(`  Allowed: ${SETTABLE_CREDENTIAL_KEYS.join(', ')}`));
+    process.exitCode = 1;
+    return;
+  }
+  await saveMcpCredentials({ [key]: value });
+  console.log(chalk.green(`✓ Saved ${key} to ~/.aiflow/credentials.json`));
+}
+
+module.exports = {
+  createTicketsCommand,
+  setCredentialCommand,
+  SETTABLE_CREDENTIAL_KEYS,
+};