@relipa/ai-flow-kit 0.2.0-beta.0 → 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,
+};

package/scripts/use.js

@@ -360,6 +360,14 @@ function backlogGet(url) {
   });
 }
 
+/**
+ * Fetch the list of projects in the Backlog space — used to let the user pick a default
+ * project for tasks created manually (no ticket to derive a project from).
+ */
+function fetchBacklogProjects(domain, apiKey) {
+  return backlogGet(`https://${domain}/api/v2/projects?apiKey=${apiKey}`);
+}
+
 /**
  * Fetch issue detail from Backlog REST API
  */
@@ -584,6 +592,64 @@ function fetchJiraIssue(domain, email, apiToken, issueKey) {
   });
 }
 
+/**
+ * `ak jira-projects [--json]` — lists the projects visible to the configured Jira account, so the
+ * user can pick a default project for tasks created from Meeting Minutes/QnA (see Vấn đề 5.1 in
+ * PM Workflow_v1.0.md). Mirrors `listBacklogProjectsCommand` above.
+ */
+function fetchJiraProjects(domain, email, apiToken) {
+  return new Promise((resolve, reject) => {
+    const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
+    const url = `https://${domain}.atlassian.net/rest/api/3/project`;
+    https
+      .get(url, { headers: { Authorization: `Basic ${auth}`, Accept: "application/json" } }, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+            return;
+          }
+          try { resolve(JSON.parse(data)); }
+          catch (e) { reject(new Error("Invalid JSON response from Jira")); }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+async function listJiraProjectsCommand(options = {}) {
+  const creds = await loadCredentials();
+  const resolved = resolveJiraCredentials(creds);
+  if (!resolved) {
+    const msg = "Jira credentials not set. Run `aiflow init --adapter jira` first.";
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: msg })); return; }
+    console.log(chalk.yellow(`⚠ ${msg}`));
+    return;
+  }
+  try {
+    const projects = await fetchJiraProjects(resolved.domain, resolved.email, resolved.apiToken);
+    const list = projects.map((p) => ({ id: p.id, key: p.key, name: p.name }));
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ ok: true, projects: list, defaultProjectKey: creds.JIRA_DEFAULT_PROJECT_KEY ?? null }));
+      return;
+    }
+    console.log(chalk.cyan(`\nJira projects (${list.length}):`));
+    for (const p of list) {
+      const isDefault = p.key === creds.JIRA_DEFAULT_PROJECT_KEY;
+      console.log(`  ${isDefault ? chalk.green("●") : " "} ${p.key}  ${chalk.gray(p.name)}  ${chalk.gray(`(id: ${p.id})`)}`);
+    }
+  } catch (err) {
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: err.message })); return; }
+    console.log(chalk.red(`✗ Could not fetch Jira projects: ${err.message}`));
+  }
+}
+
+async function setDefaultJiraProjectCommand(key) {
+  await saveMcpCredentials({ JIRA_DEFAULT_PROJECT_KEY: key });
+  console.log(chalk.green(`✓ Default Jira project set to ${key}.`));
+}
+
 /**
  * Fetch ALL comments of an issue from Jira REST API.
  */
@@ -787,11 +853,20 @@ async function manualContext(prefillId = "", options = {}) {
   // Task type — pre-select existing value if available
   const taskType = await promptForTaskType(existing.taskType, options.taskType);
 
+  // Stamp the default Backlog project (`ak backlog-set-default-project`), if one was ever set —
+  // manual tasks have no ticket to derive a project from otherwise. Kept for later use: syncing a
+  // locally-created task up to Backlog as a new issue needs to know which project it belongs to.
+  const creds = await loadCredentials();
+  const projectId = existing.projectId ?? creds.BACKLOG_DEFAULT_PROJECT_ID ?? null;
+  const projectKey = existing.projectKey ?? creds.BACKLOG_DEFAULT_PROJECT_KEY ?? null;
+
   const context = {
     taskId,
     taskType,
     title,
     description,
+    projectId,
+    projectKey,
     status: existing.status || "In Progress",
     mode: existing.mode || "auto",
     acceptanceCriteria: existing.acceptanceCriteria || [],
@@ -967,6 +1042,63 @@ async function loadCredentials() {
   return {};
 }
 
+/** Always the global file (`~/.aiflow/credentials.json`) — same path `loadCredentials` reads
+ *  first — so a value written here is picked up by every later `loadCredentials()` call. */
+function globalCredentialsPath() {
+  return path.join(os.homedir(), ".aiflow", "credentials.json");
+}
+
+/** Merges `patch` into the saved `.mcp` credentials block, creating the file if needed. */
+async function saveMcpCredentials(patch) {
+  const file = globalCredentialsPath();
+  await fs.ensureDir(path.dirname(file));
+  const data = (await fs.pathExists(file)) ? await fs.readJson(file).catch(() => ({})) : {};
+  data.mcp = { ...(data.mcp || {}), ...patch };
+  await fs.writeJson(file, data, { spaces: 2 });
+}
+
+/**
+ * `ak backlog-projects [--json]` — lists the projects in the configured Backlog space, so the
+ * user (or a headless caller like the VS Code extension) can pick one as the default project for
+ * manually-created tasks (see `manualContext` below, which stamps that default onto new tasks).
+ */
+async function listBacklogProjectsCommand(options = {}) {
+  const creds = await loadCredentials();
+  const resolved = resolveBacklogCredentials(creds);
+  if (!resolved) {
+    const msg = "Backlog credentials not set. Run `aiflow init --adapter backlog` first.";
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: msg })); return; }
+    console.log(chalk.yellow(`⚠ ${msg}`));
+    return;
+  }
+  try {
+    const projects = await fetchBacklogProjects(resolved.domain, resolved.apiKey);
+    const list = projects.map((p) => ({ id: p.id, projectKey: p.projectKey, name: p.name }));
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ ok: true, projects: list, defaultProjectId: creds.BACKLOG_DEFAULT_PROJECT_ID ?? null }));
+      return;
+    }
+    console.log(chalk.cyan(`\nBacklog projects (${list.length}):`));
+    for (const p of list) {
+      const isDefault = String(p.id) === String(creds.BACKLOG_DEFAULT_PROJECT_ID);
+      console.log(`  ${isDefault ? chalk.green("●") : " "} ${p.projectKey}  ${chalk.gray(p.name)}  ${chalk.gray(`(id: ${p.id})`)}`);
+    }
+  } catch (err) {
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: err.message })); return; }
+    console.log(chalk.red(`✗ Could not fetch Backlog projects: ${err.message}`));
+  }
+}
+
+/**
+ * `ak backlog-set-default-project <id> <key>` — saves the chosen default project, so future
+ * manually-created tasks (`ak use --manual`) get stamped with it automatically. Non-interactive —
+ * safe to spawn without a TTY (see New-ex-architecture_v1.0.md §1.1 for why that distinction matters).
+ */
+async function setDefaultBacklogProjectCommand(id, key) {
+  await saveMcpCredentials({ BACKLOG_DEFAULT_PROJECT_ID: id, BACKLOG_DEFAULT_PROJECT_KEY: key });
+  console.log(chalk.green(`✓ Default Backlog project set to ${key} (id: ${id}).`));
+}
+
 // ──────────────────────────────────────────────────────────────
 // Context persistence
 // ──────────────────────────────────────────────────────────────
@@ -1353,3 +1485,12 @@ module.exports.detectTaskTypeFromString = detectTaskTypeFromString;
 module.exports.manualContext = manualContext;
 module.exports.promptForTaskType = promptForTaskType;
 module.exports.previewTarget = previewTarget;
+module.exports.resolveBacklogCredentials = resolveBacklogCredentials;
+module.exports.fetchBacklogProjects = fetchBacklogProjects;
+module.exports.listBacklogProjectsCommand = listBacklogProjectsCommand;
+module.exports.setDefaultBacklogProjectCommand = setDefaultBacklogProjectCommand;
+module.exports.resolveJiraCredentials = resolveJiraCredentials;
+module.exports.fetchJiraProjects = fetchJiraProjects;
+module.exports.listJiraProjectsCommand = listJiraProjectsCommand;
+module.exports.setDefaultJiraProjectCommand = setDefaultJiraProjectCommand;
+module.exports.saveMcpCredentials = saveMcpCredentials;