@relipa/ai-flow-kit 0.2.0-beta.2 → 0.2.1

package/scripts/link-resolver.js

@@ -197,24 +197,41 @@ async function fetchBacklogPriorities(domain, apiKey) {
   return httpsGet(`https://${domain}/api/v2/priorities?apiKey=${apiKey}`);
 }
 
+/**
+ * Fetches a single Backlog issue — used to validate a PM-supplied "ticket cha có sẵn" before
+ * using it as `parentIssueId` for a batch of child issues (PM Workflow_v1.0.md Vấn đề 5, ticket cha).
+ * Returns the internal numeric `id` (needed for `parentIssueId`, which is NOT the issueKey).
+ */
+async function getBacklogIssue(domain, apiKey, issueIdOrKey) {
+  const issue = await httpsGet(`https://${domain}/api/v2/issues/${issueIdOrKey}?apiKey=${apiKey}`);
+  return { id: issue.id, issueKey: issue.issueKey, projectId: issue.projectId, summary: issue.summary || '' };
+}
+
 /**
  * Creates a Backlog issue. Requires an apiKey with WRITE permission — distinct from the
  * read-only key used elsewhere in this file for `ak fetch-links`/`ak use`.
  * `projectId`, `summary`, `issueTypeId`, `priorityId` are mandatory per Backlog's API.
+ *
+ * `parentIssueId` (optional) — Backlog's internal numeric issue `id` (not the `issueKey`) to
+ * link this as a child issue. ⚠️ NOT verified against a live space: requires the target project
+ * to have issue hierarchy ("Subtasking") enabled — if it isn't, Backlog rejects the request and
+ * the caller should surface the raw error rather than assume the link succeeded.
  */
-async function createBacklogIssue(domain, apiKeyWrite, { projectId, summary, description, issueTypeId, priorityId }) {
+async function createBacklogIssue(domain, apiKeyWrite, { projectId, summary, description, issueTypeId, priorityId, parentIssueId }) {
+  const payload = {
+    projectId: String(projectId),
+    summary,
+    issueTypeId: String(issueTypeId),
+    priorityId: String(priorityId),
+    description: description || '',
+  };
+  if (parentIssueId) payload.parentIssueId = String(parentIssueId);
   const issue = await httpsPost(
     `https://${domain}/api/v2/issues?apiKey=${apiKeyWrite}`,
-    {
-      projectId: String(projectId),
-      summary,
-      issueTypeId: String(issueTypeId),
-      priorityId: String(priorityId),
-      description: description || '',
-    },
+    payload,
     { bodyType: 'form' }
   );
-  return { ticketId: issue.issueKey, url: `https://${domain}/view/${issue.issueKey}`, raw: issue };
+  return { ticketId: issue.issueKey, internalId: issue.id, url: `https://${domain}/view/${issue.issueKey}`, raw: issue };
 }
 
 function jiraAuth(email, token) {
@@ -262,25 +279,44 @@ async function fetchJiraComment(domain, email, token, ticketId, commentId) {
 
 // ── Jira WRITE — issue creation (PM Workflow_v1.0.md "Vấn đề 5") ────────────
 
+/**
+ * Fetches a single Jira issue — used to validate a PM-supplied "ticket cha có sẵn" before
+ * using its key as `parent` for a batch of child issues.
+ */
+async function getJiraIssue(domain, email, token, ticketId) {
+  const issue = await httpsGet(
+    `https://${domain}/rest/api/3/issue/${ticketId}`,
+    { Authorization: jiraAuth(email, token), Accept: 'application/json' }
+  );
+  const fields = issue.fields || {};
+  return { key: issue.key, projectKey: fields.project ? fields.project.key : null, summary: fields.summary || '' };
+}
+
 /**
  * Creates a Jira issue. `apiTokenWrite`/`emailWrite` are distinct from the read-only
  * credentials used elsewhere in this file — same "separate WRITE key" policy as Backlog.
+ *
+ * `parentKey` (optional) — Jira issue key to link this as a child via `fields.parent`.
+ * ⚠️ NOT verified against a live instance: this field works directly for team-managed
+ * ("next-gen") projects; company-managed ("classic") projects may require the child's
+ * `issuetype` to be a dedicated `Subtask` type instead — if Jira rejects the request,
+ * surface the raw error rather than assume the link succeeded.
  */
-async function createJiraIssue(domain, emailWrite, apiTokenWrite, { projectKey, summary, description, issueTypeName }) {
+async function createJiraIssue(domain, emailWrite, apiTokenWrite, { projectKey, summary, description, issueTypeName, parentKey }) {
+  const fields = {
+    project: { key: projectKey },
+    summary,
+    issuetype: { name: issueTypeName || 'Task' },
+    description: {
+      type: 'doc',
+      version: 1,
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: description || '' }] }],
+    },
+  };
+  if (parentKey) fields.parent = { key: parentKey };
   const issue = await httpsPost(
     `https://${domain}/rest/api/3/issue`,
-    {
-      fields: {
-        project: { key: projectKey },
-        summary,
-        issuetype: { name: issueTypeName || 'Task' },
-        description: {
-          type: 'doc',
-          version: 1,
-          content: [{ type: 'paragraph', content: [{ type: 'text', text: description || '' }] }],
-        },
-      },
-    },
+    { fields },
     { headers: { Authorization: jiraAuth(emailWrite, apiTokenWrite), Accept: 'application/json' }, bodyType: 'json' }
   );
   return { ticketId: issue.key, url: `https://${domain}/browse/${issue.key}`, raw: issue };
@@ -365,6 +401,6 @@ module.exports = {
   fetchBacklogTicket, fetchBacklogComment,
   fetchBacklogDocument, fetchBacklogDocumentComment, fetchBacklogWiki,
   fetchJiraTicket, fetchJiraComment,
-  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue,
-  createJiraIssue,
+  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue, getBacklogIssue,
+  createJiraIssue, getJiraIssue,
 };

package/scripts/ticket-writer.js

@@ -24,7 +24,9 @@ const {
   fetchBacklogIssueTypes,
   fetchBacklogPriorities,
   createBacklogIssue,
+  getBacklogIssue,
   createJiraIssue,
+  getJiraIssue,
 } = linkResolver;
 
 // Only these keys can be written via `ak credentials set` — dedicated adapter credentials
@@ -104,13 +106,23 @@ async function pickBacklogDefaults(domain, apiKeyRead, projectId) {
  *   "target": "backlog" | "jira",
  *   "projectId": "12345",     // optional — Backlog only, overrides BACKLOG_DEFAULT_PROJECT_ID
  *   "projectKey": "PROJ",     // optional — Jira only, overrides JIRA_DEFAULT_PROJECT_KEY
+ *   "parentTicket": {         // optional — ingest-data SKILL.md § 5.6b "Ticket cha"
+ *     "mode": "create" | "existing" | "none",
+ *     "title": "...",         // required when mode === "create"
+ *     "description": "...",  // optional when mode === "create"
+ *     "existingId": "..."    // required when mode === "existing" (Backlog key/id or Jira key)
+ *   },
  *   "tasks": [
- *     { "type": "spec|coding|test|other", "title": "...", "description": "..." }
+ *     { "type": "spec|system-requirement|impact-analysis|coding|test|execute-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.
+ *
+ * When `parentTicket.mode` is "create" or "existing", every task in `tasks` is created as a
+ * child of that parent (Backlog `parentIssueId` / Jira `parent`) — see link-resolver.js for the
+ * caveat that this depends on the target project supporting issue hierarchy/subtasks.
  */
 async function createTicketsCommand(inputFile, options = {}) {
   const emit = (obj) => {
@@ -119,6 +131,7 @@ async function createTicketsCommand(inputFile, options = {}) {
       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}.`));
+      if (obj.parent) console.log(`  ${chalk.cyan('↳ parent:')} ${obj.parent.ticketId}  ${chalk.gray(obj.parent.url)}`);
       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}`);
       }
@@ -173,6 +186,34 @@ async function createTicketsCommand(inputFile, options = {}) {
       return;
     }
 
+    const parentTicket = input.parentTicket || { mode: 'none' };
+    let parentRef = null;
+    if (parentTicket.mode === 'create') {
+      try {
+        const createdParent = await createBacklogIssue(write.domain, write.apiKeyWrite, {
+          projectId,
+          summary: parentTicket.title,
+          description: parentTicket.description || '',
+          issueTypeId: defaults.defaultIssueTypeId,
+          priorityId: defaults.defaultPriorityId,
+        });
+        parentRef = { ticketId: createdParent.ticketId, internalId: createdParent.internalId, url: createdParent.url };
+      } catch (err) {
+        emit({ ok: false, error: 'parent-create-failed', message: `Không tạo được ticket cha trên Backlog: ${err.message}` });
+        process.exitCode = 1;
+        return;
+      }
+    } else if (parentTicket.mode === 'existing') {
+      try {
+        const existing = await getBacklogIssue(write.domain, write.apiKeyRead, parentTicket.existingId);
+        parentRef = { ticketId: existing.issueKey, internalId: existing.id, url: `https://${write.domain}/view/${existing.issueKey}` };
+      } catch (err) {
+        emit({ ok: false, error: 'parent-not-found', message: `Không tìm thấy ticket cha "${parentTicket.existingId}" trên Backlog: ${err.message}` });
+        process.exitCode = 1;
+        return;
+      }
+    }
+
     const results = [];
     for (const task of tasks) {
       try {
@@ -182,13 +223,14 @@ async function createTicketsCommand(inputFile, options = {}) {
           description: task.description,
           issueTypeId: task.issueTypeId || defaults.defaultIssueTypeId,
           priorityId: task.priorityId || defaults.defaultPriorityId,
+          parentIssueId: parentRef ? parentRef.internalId : undefined,
         });
         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 });
+    emit({ ok: true, target, projectId, parent: parentRef, results });
     return;
   }
 
@@ -206,6 +248,32 @@ async function createTicketsCommand(inputFile, options = {}) {
     return;
   }
 
+  const parentTicket = input.parentTicket || { mode: 'none' };
+  let parentRef = null;
+  if (parentTicket.mode === 'create') {
+    try {
+      const createdParent = await createJiraIssue(write.domain, write.emailWrite, write.apiTokenWrite, {
+        projectKey,
+        summary: parentTicket.title,
+        description: parentTicket.description || '',
+      });
+      parentRef = { ticketId: createdParent.ticketId, url: createdParent.url };
+    } catch (err) {
+      emit({ ok: false, error: 'parent-create-failed', message: `Không tạo được ticket cha trên Jira: ${err.message}` });
+      process.exitCode = 1;
+      return;
+    }
+  } else if (parentTicket.mode === 'existing') {
+    try {
+      const existing = await getJiraIssue(write.domain, write.emailWrite, write.apiTokenWrite, parentTicket.existingId);
+      parentRef = { ticketId: existing.key, url: `https://${write.domain}/browse/${existing.key}` };
+    } catch (err) {
+      emit({ ok: false, error: 'parent-not-found', message: `Không tìm thấy ticket cha "${parentTicket.existingId}" trên Jira: ${err.message}` });
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   const results = [];
   for (const task of tasks) {
     try {
@@ -214,13 +282,14 @@ async function createTicketsCommand(inputFile, options = {}) {
         summary: task.title,
         description: task.description,
         issueTypeName: task.issueType || 'Task',
+        parentKey: parentRef ? parentRef.ticketId : undefined,
       });
       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 });
+  emit({ ok: true, target, projectKey, parent: parentRef, results });
 }
 
 /**