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

package/scripts/use.js

@@ -8,11 +8,13 @@ const { select, input } = require("@inquirer/prompts");
 const stringWidth = require("string-width");
 const CATEGORY_COLOR = {
   Coding:   chalk.cyan,
+  Dev:      chalk.blueBright,
   Testing:  chalk.green,
   Analysis: chalk.yellow,
   Document: chalk.magenta,
   BA:       chalk.blue,
   QA:       chalk.greenBright,
+  PM:       chalk.redBright,
 };
 const td = (label, cat, desc) => {
   const pad = " ".repeat(Math.max(0, 20 - stringWidth(label)));
@@ -32,6 +34,15 @@ const useCommand = async function use(targets, options = {}) {
   // Normalize: accept string (legacy) or array (new multi-target)
   const targetList = Array.isArray(targets) ? targets.filter(Boolean) : (targets ? [targets] : []);
   const primaryTarget = targetList[0] || null;
+
+  // ── Preview mode: fetch + print JSON to stdout, nothing else — no save, no
+  //    prompts, no other console output (a caller like a GUI parses stdout
+  //    as JSON, so nothing may print ahead of it). Must run before every
+  //    other check/notice below, all of which write informational stdout. ──
+  if (options.preview) {
+    return await previewTarget(primaryTarget, options);
+  }
+
   const supplementaryTargets = targetList.slice(1);
 
   if (!(await fs.pathExists(STATE_FILE))) {
@@ -56,7 +67,7 @@ const useCommand = async function use(targets, options = {}) {
 
   // ── Manual entry ──
   if (options.manual) {
-    return await manualContext();
+    return await manualContext("", options);
   }
 
   // ── Load from local file ──
@@ -92,7 +103,7 @@ const useCommand = async function use(targets, options = {}) {
   console.log(
     chalk.gray("Supported: PROJ-33, APP-123, version number, --manual"),
   );
-  return await manualContext();
+  return await manualContext("", options);
 };
 
 // ──────────────────────────────────────────────────────────────
@@ -192,65 +203,87 @@ async function switchVersion(versionReq) {
 // Backlog context loader
 // ──────────────────────────────────────────────────────────────
 
-async function loadFromBacklog(issueKey, options = {}) {
-  const creds = await loadCredentials();
+/** Resolves Backlog credentials from env/config, or null if unset. */
+function resolveBacklogCredentials(creds) {
   const apiKey = process.env.BACKLOG_API_KEY || creds.BACKLOG_API_KEY;
   const spaceKey =
     process.env.BACKLOG_SPACE_KEY ||
     creds.BACKLOG_SPACE_KEY ||
     process.env.BACKLOG_DOMAIN ||
     creds.BACKLOG_DOMAIN;
+  if (!apiKey || !spaceKey) return null;
+  // spaceKey can be full domain (mycompany.backlog.com) or just the space (mycompany)
+  const domain = spaceKey.includes(".") ? spaceKey : `${spaceKey}.backlog.com`;
+  return { apiKey, domain };
+}
+
+/**
+ * Pure fetch: resolves a Backlog issue into internal context format.
+ * Throws on missing credentials or fetch failure — never prompts, never saves.
+ * Used by both `loadFromBacklog` (interactive) and `previewTarget` (headless).
+ */
+async function fetchBacklogContext(issueKey, options = {}) {
+  const creds = await loadCredentials();
+  const resolved = resolveBacklogCredentials(creds);
+  if (!resolved) {
+    throw new Error(
+      "Backlog credentials not set. Run `aiflow init --adapter backlog` or set BACKLOG_API_KEY / BACKLOG_SPACE_KEY.",
+    );
+  }
+  const { apiKey, domain } = resolved;
+
+  // Default: description only. Comments loaded only when explicitly requested.
+  const loadComments =
+    options.coms ||
+    options.withComs ||
+    options.withComments ||
+    options["with-comments"] ||
+    options.with_comments ||
+    options.cid != null ||
+    options.commentId != null ||
+    options["comment-id"] != null ||
+    options.clast != null ||
+    options.commentsLast != null ||
+    options.cfrom != null ||
+    options.commentsFrom != null ||
+    options.cto != null ||
+    options.commentsTo != null ||
+    options["comments-to"] != null;
+
+  if (loadComments) {
+    console.log(chalk.gray("  ℹ Comments requested..."));
+  }
+  const [issue, rawComments] = await Promise.all([
+    fetchBacklogIssue(domain, apiKey, issueKey),
+    loadComments
+      ? fetchBacklogComments(domain, apiKey, issueKey)
+      : Promise.resolve([]),
+  ]);
+
+  const comments = filterComments(rawComments, options);
+  if (loadComments) {
+    console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
+  }
+  return buildContextFromBacklog(issue, comments, issueKey, domain);
+}
 
-  if (!apiKey || !spaceKey) {
+async function loadFromBacklog(issueKey, options = {}) {
+  const creds = await loadCredentials();
+  if (!resolveBacklogCredentials(creds)) {
     console.log(chalk.yellow("⚠ Backlog credentials not set."));
     console.log(chalk.gray("Run: aiflow init --adapter backlog"));
     console.log(chalk.gray("Or set environment variables:"));
     console.log(chalk.gray("  BACKLOG_API_KEY=your-api-key"));
     console.log(chalk.gray("  BACKLOG_SPACE_KEY=your-space (e.g. mycompany)"));
     console.log(chalk.gray("\nFalling back to manual entry...\n"));
-    return await manualContext(issueKey);
+    return await manualContext(issueKey, options);
   }
 
-  // spaceKey can be full domain (mycompany.backlog.com) or just the space (mycompany)
-  const domain = spaceKey.includes(".") ? spaceKey : `${spaceKey}.backlog.com`;
-
   console.log(chalk.blue(`Fetching context from Backlog: ${issueKey}...`));
 
   try {
-    // Default: description only. Comments loaded only when explicitly requested.
-    const loadComments =
-      options.coms ||
-      options.withComs ||
-      options.withComments ||
-      options["with-comments"] ||
-      options.with_comments ||
-      options.cid != null ||
-      options.commentId != null ||
-      options["comment-id"] != null ||
-      options.clast != null ||
-      options.commentsLast != null ||
-      options.cfrom != null ||
-      options.commentsFrom != null ||
-      options.cto != null ||
-      options.commentsTo != null ||
-      options["comments-to"] != null;
-
-    if (loadComments) {
-      console.log(chalk.gray("  ℹ Comments requested..."));
-    }
-    const [issue, rawComments] = await Promise.all([
-      fetchBacklogIssue(domain, apiKey, issueKey),
-      loadComments
-        ? fetchBacklogComments(domain, apiKey, issueKey)
-        : Promise.resolve([]),
-    ]);
-
-    const comments = filterComments(rawComments, options);
-    if (loadComments) {
-      console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
-    }
-    const context = buildContextFromBacklog(issue, comments, issueKey, domain);
-    context.taskType = await promptForTaskType(context.taskType);
+    const context = await fetchBacklogContext(issueKey, options);
+    context.taskType = await promptForTaskType(context.taskType, options.taskType);
     context.mode = options.full ? "full" : "fast";
     await saveContext(context, options.save);
     printContextSummary(context);
@@ -258,7 +291,7 @@ async function loadFromBacklog(issueKey, options = {}) {
   } catch (err) {
     console.log(chalk.yellow(`⚠ Could not fetch from Backlog: ${err.message}`));
     console.log(chalk.gray("Falling back to manual entry...\n"));
-    await manualContext(issueKey);
+    await manualContext(issueKey, options);
   }
 }
 
@@ -395,6 +428,8 @@ function buildContextFromBacklog(issue, comments, issueKey, domain) {
 
   return {
     taskId: issueKey,
+    projectId: issue.projectId ?? null,
+    projectKey: projectKeyFromIssueKey(issueKey),
     taskType: type,
     title: issue.summary || "",
     description: issue.description || "",
@@ -430,13 +465,67 @@ function buildContextFromBacklog(issue, comments, issueKey, domain) {
 // Jira context loader
 // ──────────────────────────────────────────────────────────────
 
-async function loadFromJira(issueKey, options = {}) {
-  const creds = await loadCredentials();
+/** Resolves Jira credentials from env/config, or null if unset. */
+function resolveJiraCredentials(creds) {
   const apiToken = process.env.JIRA_API_TOKEN || creds.JIRA_API_TOKEN;
   const email = process.env.JIRA_EMAIL || creds.JIRA_EMAIL;
   const domain = process.env.JIRA_DOMAIN || creds.JIRA_DOMAIN;
+  if (!apiToken || !email || !domain) return null;
+  return { apiToken, email, domain };
+}
+
+/**
+ * Pure fetch: resolves a Jira issue into internal context format.
+ * Throws on missing credentials or fetch failure — never prompts, never saves.
+ * Used by both `loadFromJira` (interactive) and `previewTarget` (headless).
+ */
+async function fetchJiraContext(issueKey, options = {}) {
+  const creds = await loadCredentials();
+  const resolved = resolveJiraCredentials(creds);
+  if (!resolved) {
+    throw new Error(
+      "Jira credentials not set. Set JIRA_API_TOKEN, JIRA_EMAIL, JIRA_DOMAIN.",
+    );
+  }
+  const { apiToken, email, domain } = resolved;
+
+  const loadComments =
+    options.coms ||
+    options.withComs ||
+    options.withComments ||
+    options["with-comments"] ||
+    options.with_comments ||
+    options.cid != null ||
+    options.commentId != null ||
+    options["comment-id"] != null ||
+    options.clast != null ||
+    options.commentsLast != null ||
+    options.cfrom != null ||
+    options.commentsFrom != null ||
+    options.cto != null ||
+    options.commentsTo != null ||
+    options["comments-to"] != null;
+
+  if (loadComments) {
+    console.log(chalk.gray("  ℹ Comments requested..."));
+  }
+  const [issue, rawComments] = await Promise.all([
+    fetchJiraIssue(domain, email, apiToken, issueKey),
+    loadComments
+      ? fetchJiraComments(domain, email, apiToken, issueKey)
+      : Promise.resolve([]),
+  ]);
+
+  const comments = filterComments(rawComments, options);
+  if (loadComments) {
+    console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
+  }
+  return buildContextFromJira(issue, comments, issueKey, domain);
+}
 
-  if (!apiToken || !email || !domain) {
+async function loadFromJira(issueKey, options = {}) {
+  const creds = await loadCredentials();
+  if (!resolveJiraCredentials(creds)) {
     console.log(chalk.yellow("⚠ Jira credentials not set."));
     console.log(chalk.gray("Run: aiflow init --adapter jira"));
     console.log(
@@ -445,45 +534,14 @@ async function loadFromJira(issueKey, options = {}) {
       ),
     );
     console.log(chalk.gray("\nFalling back to manual entry...\n"));
-    return await manualContext(issueKey);
+    return await manualContext(issueKey, options);
   }
 
   console.log(chalk.blue(`Fetching context from Jira: ${issueKey}...`));
 
   try {
-    const loadComments =
-      options.coms ||
-      options.withComs ||
-      options.withComments ||
-      options["with-comments"] ||
-      options.with_comments ||
-      options.cid != null ||
-      options.commentId != null ||
-      options["comment-id"] != null ||
-      options.clast != null ||
-      options.commentsLast != null ||
-      options.cfrom != null ||
-      options.commentsFrom != null ||
-      options.cto != null ||
-      options.commentsTo != null ||
-      options["comments-to"] != null;
-
-    if (loadComments) {
-      console.log(chalk.gray("  ℹ Comments requested..."));
-    }
-    const [issue, rawComments] = await Promise.all([
-      fetchJiraIssue(domain, email, apiToken, issueKey),
-      loadComments
-        ? fetchJiraComments(domain, email, apiToken, issueKey)
-        : Promise.resolve([]),
-    ]);
-
-    const comments = filterComments(rawComments, options);
-    if (loadComments) {
-      console.log(chalk.gray(`  ℹ Comments: ${rawComments.length} fetched, ${comments.length} kept after filtering.`));
-    }
-    const context = buildContextFromJira(issue, comments, issueKey, domain);
-    context.taskType = await promptForTaskType(context.taskType);
+    const context = await fetchJiraContext(issueKey, options);
+    context.taskType = await promptForTaskType(context.taskType, options.taskType);
     context.mode = options.full ? "full" : "fast";
     await saveContext(context, options.save);
     printContextSummary(context);
@@ -491,7 +549,7 @@ async function loadFromJira(issueKey, options = {}) {
   } catch (err) {
     console.log(chalk.yellow(`⚠ Could not fetch from Jira: ${err.message}`));
     console.log(chalk.gray("Falling back to manual entry...\n"));
-    await manualContext(issueKey);
+    await manualContext(issueKey, options);
   }
 }
 
@@ -590,6 +648,8 @@ function buildContextFromJira(issue, comments, issueKey, domain) {
 
   return {
     taskId: issueKey,
+    projectId: fields.project?.id ?? null,
+    projectKey: fields.project?.key ?? projectKeyFromIssueKey(issueKey),
     taskType: type,
     title: fields.summary || "",
     description:
@@ -623,7 +683,13 @@ function buildContextFromJira(issue, comments, issueKey, domain) {
 // Task type selector — shared by all loaders
 // ──────────────────────────────────────────────────────────────
 
-async function promptForTaskType(detectedDefault) {
+/**
+ * Returns `explicit` immediately (no prompt) when the caller already knows the
+ * task type — e.g. `--task-type` was passed by a headless caller. Otherwise
+ * falls back to the interactive `select()` prompt as before.
+ */
+async function promptForTaskType(detectedDefault, explicit) {
+  if (explicit != null && explicit !== "") return explicit;
   return await select({
     message: "Task type:",
     choices: [
@@ -633,10 +699,12 @@ async function promptForTaskType(detectedDefault) {
       { name: td("▶️  Execute Test",    "Testing",  "Run existing TC scripts (4-gate flow)"),             value: "execute" },
       { name: td("📋 Create Spec",      "BA",       "Create UC Spec from raw requirements (4-gate BA)"),  value: "create-spec" },
       { name: td("✅ Create TestCase",  "QA",       "Create Test Cases from requirements (4-gate QA)"),   value: "create-testcase" },
+      { name: td("📐 Create System Requirement", "Dev", "Bridge UC Spec → System Requirement (blocks coding Gate 1, 2-gate)"), value: "create-system-requirement" },
       { name: td("🔍 Investigation",    "Analysis", "Investigate, analyze root cause"),                   value: "investigation" },
       { name: td("📊 Impact Analysis",  "Analysis", "Assess scope and risk of changes"),                  value: "impact-analysis" },
       { name: td("📖 Documentation",    "Document", "Write docs, README, API reference"),                 value: "documentation" },
       { name: td("📝 Generate Doc/Spec", "Document", "Generate new documentation/Spec (2-gate)"),          value: "gen-doc" },
+      { name: td("📥 Ingest Data",      "PM",       "Ingest Backlog/Jira/SharePoint link or pasted text into AK-Docs logs (2-gate)"), value: "ingest-data" },
     ],
     default: detectedDefault || "feature",
   });
@@ -646,7 +714,7 @@ async function promptForTaskType(detectedDefault) {
 // Manual context entry
 // ──────────────────────────────────────────────────────────────
 
-async function manualContext(prefillId = "") {
+async function manualContext(prefillId = "", options = {}) {
   // Load existing context for pre-fill (Edit mode)
   let existing = {};
   const currentPath = path.join(CONTEXT_DIR, "current.json");
@@ -655,65 +723,69 @@ async function manualContext(prefillId = "") {
   }
 
   const isEdit = !!existing.taskId;
-  if (isEdit) {
-    console.log(chalk.cyan("\nEdit Context\n"));
-    console.log(
-      chalk.gray("Press Enter to keep existing value shown in [brackets]\n"),
-    );
-  } else {
-    console.log(chalk.cyan("\nManual Context Entry\n"));
+  // Headless callers (extension popup, scripts) pass fields as flags — skip
+  // the corresponding inquirer prompt entirely when a field is supplied.
+  if (options.title == null && options.description == null && options.taskType == null) {
+    if (isEdit) {
+      console.log(chalk.cyan("\nEdit Context\n"));
+      console.log(
+        chalk.gray("Press Enter to keep existing value shown in [brackets]\n"),
+      );
+    } else {
+      console.log(chalk.cyan("\nManual Context Entry\n"));
+    }
   }
 
   // Ticket ID
-  const defaultId = prefillId || existing.taskId || "";
-  const idHint = defaultId ? chalk.gray(` [${defaultId}]`) : "";
-  const idInput = await input({
-    message: `Ticket ID (e.g. PROJ-33)${idHint}:`,
-    default: "",
-  });
-  const taskId = idInput.trim() || defaultId;
+  const defaultId = options.ticketId || prefillId || existing.taskId || "";
+  let taskId;
+  if (options.ticketId != null) {
+    taskId = options.ticketId;
+  } else {
+    const idHint = defaultId ? chalk.gray(` [${defaultId}]`) : "";
+    const idInput = await input({
+      message: `Ticket ID (e.g. PROJ-33)${idHint}:`,
+      default: "",
+    });
+    taskId = idInput.trim() || defaultId;
+  }
 
   // Title
-  const defaultTitle = existing.title || "";
-  const titlePreview =
-    defaultTitle.length > 50
-      ? defaultTitle.substring(0, 50) + "…"
-      : defaultTitle;
-  const titleHint = defaultTitle ? chalk.gray(` [${titlePreview}]`) : "";
-  const titleInput = await input({
-    message: `Title${titleHint}:`,
-    default: "",
-  });
-  const title = titleInput.trim() || defaultTitle;
+  let title;
+  if (options.title != null) {
+    title = options.title;
+  } else {
+    const defaultTitle = existing.title || "";
+    const titlePreview =
+      defaultTitle.length > 50
+        ? defaultTitle.substring(0, 50) + "…"
+        : defaultTitle;
+    const titleHint = defaultTitle ? chalk.gray(` [${titlePreview}]`) : "";
+    const titleInput = await input({
+      message: `Title${titleHint}:`,
+      default: "",
+    });
+    title = titleInput.trim() || defaultTitle;
+  }
 
   // Description
-  const defaultDesc = existing.description || "";
-  const descPreview =
-    defaultDesc.length > 60 ? defaultDesc.substring(0, 60) + "…" : defaultDesc;
-  const descHint = defaultDesc ? chalk.gray(` [${descPreview}]`) : "";
-  const descInput = await input({
-    message: `Description (brief)${descHint}:`,
-    default: "",
-  });
-  const description = descInput.trim() || defaultDesc;
+  let description;
+  if (options.description != null) {
+    description = options.description;
+  } else {
+    const defaultDesc = existing.description || "";
+    const descPreview =
+      defaultDesc.length > 60 ? defaultDesc.substring(0, 60) + "…" : defaultDesc;
+    const descHint = defaultDesc ? chalk.gray(` [${descPreview}]`) : "";
+    const descInput = await input({
+      message: `Description (brief)${descHint}:`,
+      default: "",
+    });
+    description = descInput.trim() || defaultDesc;
+  }
 
   // Task type — pre-select existing value if available
-  const taskType = await select({
-    message: "Task type:",
-    choices: [
-      { name: td("🐛 Bug Fix",         "Coding",   "Fix bugs, crashes, regressions"),                    value: "bug-fix" },
-      { name: td("✨ Feature",          "Coding",   "Build new features, user stories"),                  value: "feature" },
-      { name: td("🔄 Refactor",         "Coding",   "Improve code without behavior change"),              value: "refactor" },
-      { name: td("▶️  Execute Test",    "Testing",  "Run existing TC scripts (4-gate flow)"),             value: "execute" },
-      { name: td("📋 Create Spec",      "BA",       "Create UC Spec from raw requirements (4-gate BA)"),  value: "create-spec" },
-      { name: td("✅ Create TestCase",  "QA",       "Create Test Cases from requirements (4-gate QA)"),   value: "create-testcase" },
-      { name: td("🔍 Investigation",    "Analysis", "Investigate, analyze root cause"),                   value: "investigation" },
-      { name: td("📊 Impact Analysis",  "Analysis", "Assess scope and risk of changes"),                  value: "impact-analysis" },
-      { name: td("📖 Documentation",    "Document", "Write docs, README, API reference"),                 value: "documentation" },
-      { name: td("📝 Generate Doc/Spec", "Document", "Generate new documentation/Spec (2-gate)"),          value: "gen-doc" },
-    ],
-    default: existing.taskType || undefined,
-  });
+  const taskType = await promptForTaskType(existing.taskType, options.taskType);
 
   const context = {
     taskId,
@@ -765,13 +837,51 @@ async function loadFromFile(filePath, options = {}) {
   context.mode = options.full ? "full" : "fast";
 
   // Prompt for task type
-  context.taskType = await promptForTaskType(context.taskType);
+  context.taskType = await promptForTaskType(context.taskType, options.taskType);
 
   await saveContext(context, options.save);
   printContextSummary(context);
   await suggestNextStep();
 }
 
+/**
+ * Preview mode (`ak use <target> --preview`): fetches a ticket and prints its
+ * resolved context as JSON to stdout — no save, no prompts, no other output.
+ * Lets a GUI caller (e.g. the VS Code extension's popup) show fetched
+ * Title/Description/Project ID/Key/detected Task Type before committing.
+ */
+async function previewTarget(target, options = {}) {
+  if (!target) {
+    process.stderr.write("ak use --preview requires a ticket ID or Backlog/Jira URL.\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  let issueKey = target;
+  let adapter;
+  if (isTicketId(target)) {
+    adapter = await resolveTicketAdapter();
+  } else if (isBacklogUrl(target)) {
+    issueKey = extractBacklogId(target);
+    adapter = "backlog";
+  } else {
+    process.stderr.write(`ak use --preview only supports a ticket ID or Backlog URL, got: ${target}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const context =
+      adapter === "jira"
+        ? await fetchJiraContext(issueKey, options)
+        : await fetchBacklogContext(issueKey, options);
+    process.stdout.write(JSON.stringify(context) + "\n");
+  } catch (err) {
+    process.stderr.write(`Error fetching preview: ${err.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
 /**
  * Build a minimal context object from arbitrary plain-text file content.
  * Tries to detect ticket ID (e.g. PROJ-33, APP-123) and a title from the first non-blank line.
@@ -939,6 +1049,8 @@ async function saveContext(context, saveName) {
     const state = await fs.readJson(STATE_FILE);
     state.current_context = context.taskId;
     state.current_context_type = context.taskType;
+    state.current_context_project_id = context.projectId ?? null;
+    state.current_context_project_key = context.projectKey ?? null;
     await fs.writeJson(STATE_FILE, state);
   }
 }
@@ -985,9 +1097,20 @@ function extractRelatedTickets(text) {
   return [...new Set(matches)];
 }
 
+/** Both Backlog and Jira issue keys are PROJECTKEY-NUMBER — strip the trailing -NUMBER. */
+function projectKeyFromIssueKey(issueKey) {
+  const match = String(issueKey || "").match(/^([A-Z][A-Z0-9_]+)-\d+$/);
+  return match ? match[1] : null;
+}
+
 function printContextSummary(context) {
   console.log(chalk.green("\n✓ Context loaded\n"));
   console.log(`  ${chalk.white("Ticket:")}   ${context.taskId}`);
+  if (context.projectKey || context.projectId != null) {
+    console.log(
+      `  ${chalk.white("Project:")}  ${context.projectKey || "(unknown key)"}${context.projectId != null ? chalk.gray(` (id: ${context.projectId})`) : ""}`,
+    );
+  }
   console.log(`  ${chalk.white("Type:")}     ${context.taskType}`);
   console.log(
     `  ${chalk.white("Title:")}    ${context.title.substring(0, 70)}`,
@@ -1227,3 +1350,6 @@ async function enrichWithSupplementary(supplementaryTargets) {
 module.exports = useCommand;
 module.exports.loadCredentials = loadCredentials;
 module.exports.detectTaskTypeFromString = detectTaskTypeFromString;
+module.exports.manualContext = manualContext;
+module.exports.promptForTaskType = promptForTaskType;
+module.exports.previewTarget = previewTarget;