deuk-agent-rule 2.5.13 → 3.3.2

package/scripts/cli-utils.mjs

@@ -1,19 +1,89 @@
-import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
-import { basename, dirname, join, relative } from "path";
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync, unlinkSync, rmSync } from "fs";
+import { basename, dirname, join, relative, resolve } from "path";
+import { pathToFileURL } from "url";
+import { createInterface } from "readline";
 import YAML from "yaml";
 
+/** Converts an absolute path to a clickable file:/// URI */
+export function toFileUri(absPath) {
+  return pathToFileURL(absPath).href;
+}
+
 export const AGENT_ROOT_DIR = ".deuk-agent";
 export const TICKET_SUBDIR = "tickets";
 export const TEMPLATE_SUBDIR = "templates";
 export const RULES_SUBDIR = "rules";
+export const WORKFLOW_MODE_PLAN = "plan";
+export const WORKFLOW_MODE_EXECUTE = "execute";
 
 export const TICKET_DIR_NAME = `${AGENT_ROOT_DIR}/${TICKET_SUBDIR}`;
 export const TICKET_INDEX_FILENAME = "INDEX.json";
 export const TICKET_LIST_FILENAME = "TICKET_LIST.md";
-export const TICKET_LIST_TEMPLATE_FILENAME = "TICKET_LIST.template.md";
+export const DOCS_SUBDIR = "docs";
+export const PLANS_SUBDIR = "plan";
+export const PLAN_LINKS_DIR = `${AGENT_ROOT_DIR}/${DOCS_SUBDIR}/${PLANS_SUBDIR}`;
+
+export const LEGACY_TEMPLATE_DIR = ".deuk-agent-templates";
+export const LEGACY_TICKET_DIR = ".deuk-agent-ticket";
+export const LEGACY_TICKET_DIR_PLURAL = ".deuk-agent-tickets";
+export const LEGACY_TICKET_DIR_ROOT = "ticket";
+export const LEGACY_CONFIG_FILE = ".deuk-agent-rule.config.json";
+export const LEGACY_IGNORE_DIR = `${AGENT_ROOT_DIR}/tickets/`;
+export const ARCHIVE_YEAR_MONTH_RE = /^\d{4}-\d{2}$/;
+export const ARCHIVE_DAY_RE = /^\d{2}$/;
+
+const LEGACY_TICKET_GROUPS = new Set([
+  LEGACY_TICKET_DIR,
+  LEGACY_TICKET_DIR_PLURAL,
+  "ticket",
+  "tickets"
+]);
+
+/**
+ * Computes the canonical repository-relative path for a ticket based on its state.
+ */
+export function computeTicketPath(entry) {
+  const isArchived = entry.status === "archived";
+  const group = normalizeTicketGroup(entry.group, "sub");
+  const fileStem = entry.fileName
+    ? String(entry.fileName).replace(/\.md$/i, "")
+    : (entry.group === TICKET_SUBDIR && entry.topic ? entry.topic : entry.id);
+
+  if (!isArchived && group === TICKET_SUBDIR) {
+    return [TICKET_DIR_NAME, `${fileStem}.md`].join("/");
+  }
+
+  if (isArchived && entry.archiveYearMonth && entry.archiveDay) {
+    return [
+      TICKET_DIR_NAME,
+      "archive",
+      group,
+      entry.archiveYearMonth,
+      entry.archiveDay,
+      `${fileStem}.md`
+    ].join("/");
+  }
+
+  const parts = [
+    TICKET_DIR_NAME,
+    isArchived ? "archive" : null,
+    group,
+    `${fileStem}.md`
+  ].filter(Boolean);
+  return parts.join("/");
+}
+
+export function normalizeTicketGroup(rawGroup, fallback = "sub") {
+  const value = String(rawGroup || "").trim();
+  if (!value) return fallback;
+  if (value.includes("/") || value.startsWith("TICKET-") && value.includes(".md")) return fallback;
+  if (value.endsWith(".md")) return fallback;
+  if (value.endsWith(".markdown")) return fallback;
+  if (LEGACY_TICKET_GROUPS.has(value)) return fallback;
+  return value;
+}
 
 export const INIT_CONFIG_FILENAME = `${AGENT_ROOT_DIR}/config.json`;
-export const LEGACY_INIT_CONFIG_FILENAME = ".deuk-agent-rule.config.json";
 export const INIT_CONFIG_VERSION = 1;
 
 export const STACKS = [
@@ -27,42 +97,176 @@ export const STACKS = [
 
 export const AGENT_TOOLS = [
   { label: "Cursor (Rule System)", value: "cursor" },
+  { label: "GitHub Copilot", value: "copilot" },
+  { label: "Codex / OpenAI", value: "codex" },
   { label: "Gemini / Antigravity", value: "gemini" },
   { label: "Claude / Dev", value: "claude" },
 ];
 
+export const SPOKE_REGISTRY = [
+  { id: "cursor", detect: (cwd) => existsSync(join(cwd, ".cursor")), legacy: ".cursorrules", target: ".cursor/rules/deuk-agent.mdc", format: "mdc" },
+  { id: "claude", detect: (cwd) => existsSync(join(cwd, "CLAUDE.md")) || existsSync(join(cwd, ".claude")), legacy: "CLAUDE.md", target: ".claude/rules/deuk-agent.md", format: "markdown" },
+  { id: "copilot", detect: (cwd, tools = []) => tools.includes("copilot") || existsSync(join(cwd, ".github")), legacy: null, target: ".github/copilot-instructions.md", format: "markdown" },
+  { id: "codex", detect: (cwd, tools = []) => tools.includes("codex") || existsSync(join(cwd, ".codex")), legacy: null, target: ".codex/AGENTS.md", format: "markdown" },
+  { id: "windsurf", detect: (cwd) => existsSync(join(cwd, ".windsurf")), legacy: ".windsurfrules", target: ".windsurf/rules/deuk-agent.md", format: "markdown" },
+  { id: "jetbrains", detect: (cwd) => existsSync(join(cwd, ".aiassistant")) || existsSync(join(cwd, ".idea")), legacy: null, target: ".aiassistant/rules/deuk-agent.md", format: "markdown" },
+  { id: "antigravity", detect: (cwd, tools = []) => tools.includes("gemini") || existsSync(join(cwd, "GEMINI.md")) || existsSync(join(cwd, ".gemini")) || existsSync(join(cwd, ".mcp.json")), legacy: "GEMINI.md", target: "AGENTS.md", format: "markdown" }
+];
+
+export const DOC_LANGUAGE_CHOICES = [
+  { label: "Auto (match system locale)", value: "auto" },
+  { label: "Korean", value: "ko" },
+  { label: "English", value: "en" },
+];
+
+export function normalizeDocsLanguage(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized || normalized === "auto") return "auto";
+  if (normalized.startsWith("ko") || normalized === "kr" || normalized === "korean") return "ko";
+  if (normalized.startsWith("en") || normalized === "english") return "en";
+  return "auto";
+}
+
+export function inferDocsLanguageFromEnv(env = process.env) {
+  const locale = String(env.LANG || env.LC_ALL || env.LC_MESSAGES || "").toLowerCase();
+  if (locale.includes("ko")) return "ko";
+  return "en";
+}
+
+export function inferDocsLanguageFromText(text) {
+  const src = String(text || "");
+  const hangulCount = (src.match(/[\u3131-\u318e\uac00-\ud7a3]/g) || []).length;
+  if (hangulCount >= 2) return "ko";
+
+  const latinWords = src.match(/[A-Za-z][A-Za-z'-]*/g) || [];
+  if (latinWords.length >= 2) return "en";
+
+  return null;
+}
+
+export function resolveDocsLanguage(value, env = process.env) {
+  const normalized = normalizeDocsLanguage(value);
+  if (normalized === "auto") return inferDocsLanguageFromEnv(env);
+  return normalized;
+}
+
+export function selectLocalizedTemplatePath(baseDir, templateName, docsLanguage = "en") {
+  const normalized = resolveDocsLanguage(docsLanguage);
+  const localizedName = `${templateName.replace(/\.md$/i, "")}.${normalized}.md`;
+  const localizedPath = join(baseDir, localizedName);
+  if (existsSync(localizedPath)) return localizedPath;
+  return join(baseDir, templateName);
+}
+
 export function loadInitConfig(cwd) {
   const p = join(cwd, INIT_CONFIG_FILENAME);
-  const legacyP = join(cwd, LEGACY_INIT_CONFIG_FILENAME);
-  
-  let target = existsSync(p) ? p : (existsSync(legacyP) ? legacyP : null);
-  if (!target) return null;
+  if (!existsSync(p)) return null;
+
+  let target = p;
 
   try {
     const j = JSON.parse(readFileSync(target, "utf8"));
     if (j.version !== INIT_CONFIG_VERSION) return null;
+    if (!j.docsLanguage) j.docsLanguage = "auto";
+    const workflowMode = normalizeWorkflowMode(j.workflowMode ?? j.approvalState);
+    j.workflowMode = workflowMode;
+    j.approvalState = workflowMode === WORKFLOW_MODE_EXECUTE ? "approved" : "pending";
     return j;
-  } catch {
+  } catch (err) {
+    if (process.env.DEBUG) console.warn(`[DEBUG] Failed to parse config ${target}:`, err);
     return null;
   }
 }
 
 export function writeInitConfig(cwd, opts) {
   const p = join(cwd, INIT_CONFIG_FILENAME);
+  const dir = dirname(p);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const existing = loadInitConfig(cwd) || {};
+  const workflowMode = normalizeWorkflowMode(opts.workflowMode ?? opts.workflow ?? opts.approvalState ?? opts.approval);
   const data = {
     version: INIT_CONFIG_VERSION,
-    agentsMode: opts.agents || "inject",
-    stack: opts.stack,
-    agentTools: opts.agentTools,
-    shareTickets: !!opts.shareTickets,
-    remoteSync: !!opts.remoteSync,
+    agentsMode: opts.agents ?? existing.agentsMode ?? "inject",
+    workflowMode,
+    approvalState: workflowMode === WORKFLOW_MODE_EXECUTE ? "approved" : "pending",
+    stack: opts.stack ?? existing.stack,
+    agentTools: opts.agentTools ?? existing.agentTools,
+    docsLanguage: normalizeDocsLanguage(opts.docsLanguage ?? existing.docsLanguage ?? "auto"),
+    shareTickets: opts.shareTickets ?? existing.shareTickets ?? false,
+    remoteSync: opts.remoteSync ?? existing.remoteSync ?? false,
     pipelineUrl: opts.pipelineUrl,
-    ignoreDirs: opts.ignoreDirs || DEFAULT_IGNORE_DIRS,
+    ignoreDirs: opts.ignoreDirs || existing.ignoreDirs || DEFAULT_IGNORE_DIRS,
     updatedAt: new Date().toISOString(),
   };
   writeFileSync(p, JSON.stringify(data, null, 2), "utf8");
 }
 
+export function normalizeWorkflowMode(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) return WORKFLOW_MODE_PLAN;
+  if (["execute", "approved", "approval", "apply", "apply-changes"].includes(normalized)) {
+    return WORKFLOW_MODE_EXECUTE;
+  }
+  if (["plan", "pending", "review", "prepare", "prepare-only"].includes(normalized)) {
+    return WORKFLOW_MODE_PLAN;
+  }
+  return normalized === WORKFLOW_MODE_EXECUTE ? WORKFLOW_MODE_EXECUTE : WORKFLOW_MODE_PLAN;
+}
+
+export function isWorkflowExecute(opts = {}, savedConfig = null) {
+  return normalizeWorkflowMode(
+    opts.workflowMode ??
+    opts.workflow ??
+    opts.approval ??
+    opts.approvalState ??
+    savedConfig?.workflowMode ??
+    savedConfig?.approvalState
+  ) === WORKFLOW_MODE_EXECUTE;
+}
+
+/**
+ * Resolves the final workflow mode by checking opts, then saved config, with fallback.
+ */
+export function resolveWorkflowMode(opts = {}, savedConfig = null) {
+  return normalizeWorkflowMode(
+    opts.workflowMode ??
+    opts.workflow ??
+    opts.approval ??
+    opts.approvalState ??
+    savedConfig?.workflowMode ??
+    savedConfig?.approvalState
+  );
+}
+
+/**
+ * Strips dynamically appended rule modules from content.
+ */
+export function pruneRuleModules(content) {
+  const marker = "<!-- RULE MODULE: ";
+  const idx = content.indexOf(marker);
+  if (idx !== -1) {
+    return content.substring(0, idx).trimEnd();
+  }
+  return content.trimEnd();
+}
+
+/**
+ * Higher-order function to wrap interactive readline sessions.
+ */
+export async function withReadline(callback) {
+  if (!process.stdout.isTTY) {
+    throw new Error("Interactive terminal required.");
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await callback(rl);
+  } finally {
+    rl.close();
+  }
+}
+
 export function toPosixPath(p) {
   return p.replace(/\\/g, "/");
 }
@@ -74,7 +278,9 @@ export function toRepoRelativePath(cwd, absPath) {
 export function toSlug(input) {
   return String(input || "")
     .toLowerCase()
-    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "") || "ticket";
 }
 
@@ -94,7 +300,7 @@ export function makeEntryId() {
 
 export function findFileRecursively(dir, fileName) {
   if (!existsSync(dir)) return null;
-  const entries = readdirSync(dir, { withFileTypes: true });
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
   for (const entry of entries) {
     const res = join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -109,20 +315,31 @@ export function findFileRecursively(dir, fileName) {
 
 export function detectProjectFromBody(body) {
   const content = String(body || "");
-  const metaMatch = content.match(/^project:\s*(.+)$/mi);
-  if (metaMatch) return metaMatch[1].trim();
-
-  const headerMatch = content.match(/^##?\s+Project:\s*(.+)$/mi);
-  if (headerMatch) return headerMatch[1].trim();
-
-  const legacyMatch = content.match(/\b(YourProject)\b/i);
-  return legacyMatch ? legacyMatch[1] : "global";
+  const lines = content.split("\n");
+  for (const line of lines) {
+    const l = line.trim();
+    if (l.toLowerCase().startsWith("project:")) {
+      return l.split(":")[1].trim();
+    }
+    if (l.startsWith("# Project:") || l.startsWith("## Project:")) {
+      return l.split(":")[1].trim();
+    }
+  }
+  return "global";
 }
 
 export function deriveTopicFromBaseName(baseName) {
-  const raw = String(baseName || "").replace(/\.md$/i, "");
-  const topic = raw.replace(/-\d{8}-\d{6}$/i, "");
-  return toSlug(topic || raw || "ticket");
+  const raw = String(baseName || "").split(".")[0];
+  // Remove trailing timestamp if present (e.g. topic-20260426-071208)
+  const parts = raw.split("-");
+  if (parts.length >= 3) {
+    const last = parts[parts.length - 1];
+    const prev = parts[parts.length - 2];
+    if (last.length === 6 && prev.length === 8) {
+      return parts.slice(0, -2).join("-");
+    }
+  }
+  return toSlug(raw);
 }
 
 export function resolveReferencedTicketPath(opts) {
@@ -141,38 +358,71 @@ export function inferRefTitleAndTopic(opts) {
   let body = "";
   try {
     body = readFileSync(refAbs, "utf8");
-  } catch {
-    body = "";
+  } catch (err) {
+    if (process.env.DEBUG) console.warn(`[DEBUG] Failed to read ref ${refAbs}:`, err);
+    return null;
   }
 
-  const taskTitleMatch = body.match(/^##\s+Task:\s*(.+)$/m);
-  const headingMatch = body.match(/^#\s+(.+)$/m);
-  const base = basename(refAbs).replace(/\.[^.]+$/, "");
-
-  const title = (taskTitleMatch && taskTitleMatch[1]) || (headingMatch && headingMatch[1]) || base;
-  const topic = toSlug(title || base);
+  const lines = body.split("\n");
+  let title = "";
+  for (const line of lines) {
+    const l = line.trim();
+    if (l.startsWith("## Task:")) {
+      title = l.replace("## Task:", "").trim();
+      break;
+    }
+    if (l.startsWith("# ")) {
+      title = l.replace("# ", "").trim();
+      break;
+    }
+  }
 
+  const base = basename(refAbs).split(".")[0];
+  const finalTitle = title || base;
   return {
-    title: String(title || base).trim(),
-    topic,
+    title: String(finalTitle).trim(),
+    topic: toSlug(finalTitle),
   };
 }
 
 export function parseFrontMatter(content) {
-  const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!match) return { meta: {}, content };
-  try {
-    const meta = YAML.parse(match[1]);
-    return { meta: meta || {}, content: match[2] };
-  } catch (e) {
-    console.error("YAML Parse Error:", e);
+  const lines = content.split("\n");
+  if (lines.length < 3 || lines[0].trim() !== "---") {
     return { meta: {}, content };
   }
+
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      endIdx = i;
+      break;
+    }
+  }
+
+  if (endIdx === -1) return { meta: {}, content };
+
+  const metaStr = lines.slice(1, endIdx).join("\n");
+  const bodyStr = lines.slice(endIdx + 1).join("\n");
+  // Let YAML.parse throw if malformed (intentional behavior change to prevent data loss)
+  const meta = YAML.parse(metaStr); 
+  return { meta: meta || {}, content: bodyStr };
 }
 
 export function stringifyFrontMatter(meta, content) {
-  const yamlStr = YAML.stringify(meta).trim();
-  return `---\n${yamlStr}\n---\n\n${content.trim()}\n`;
+  const cleanMeta = { ...meta };
+  // Remove redundant or default fields to keep frontmatter slim
+  delete cleanMeta.topic;
+  if (cleanMeta.project === 'global') delete cleanMeta.project;
+  if (!cleanMeta.submodule) delete cleanMeta.submodule;
+  
+  // Normalize date format if it looks like an ISO string
+  if (typeof cleanMeta.createdAt === 'string' && cleanMeta.createdAt.includes('T')) {
+    cleanMeta.createdAt = cleanMeta.createdAt.replace('T', ' ').split('.')[0];
+  }
+
+  const yamlStr = YAML.stringify(cleanMeta).trim();
+  // Double newline after frontmatter to ensure markdown rendering integrity
+  return `---\n${yamlStr}\n---\n\n\n${content.trim()}\n`;
 }
 
 /**
@@ -213,29 +463,101 @@ export async function checkUpdateNotifier() {
 export const DEFAULT_IGNORE_DIRS = ["node_modules", ".git", ".deuk-agent", "tmp", "temp", ".tmp", ".cache"];
 
 /**
- * Recursively finds all directories containing deuk-agent ticket structures.
+ * Resolves all potential ticket directories for a given path.
+ * Returns { primary, legacy: [] }
  */
-export function discoverAllSubmodules(baseCwd, ignoreDirs = DEFAULT_IGNORE_DIRS, out = new Set()) {
-  if (!existsSync(baseCwd)) return Array.from(out);
+export function resolveTicketSystemPaths(cwd) {
+  return {
+    primary: join(cwd, AGENT_ROOT_DIR, TICKET_SUBDIR),
+    legacy: []
+  };
+}
 
-  const hasLegacy1 = existsSync(join(baseCwd, ".deuk-agent-ticket"));
-  const hasLegacy2 = existsSync(join(baseCwd, ".deuk-agent-tickets"));
-  const hasNew = existsSync(join(baseCwd, AGENT_ROOT_DIR, TICKET_SUBDIR));
+/**
+ * Detects the closest active ticket directory by traversing upwards.
+ */
+export function detectConsumerTicketDir(startDir, opts = {}) {
+  let curr = resolve(startDir);
+  while (curr && curr !== dirname(curr)) {
+    const paths = resolveTicketSystemPaths(curr);
+    if (existsSync(paths.primary)) return paths.primary;
+    if (paths.legacy.length > 0) return paths.legacy[0];
+    curr = dirname(curr);
+  }
+  return opts.createIfMissing ? resolveTicketSystemPaths(startDir).primary : null;
+}
 
-  if (hasLegacy1 || hasLegacy2 || hasNew) {
+/**
+ * Unified workspace/submodule discovery.
+ */
+export function discoverAllWorkspaces(baseCwd, ignoreDirs = DEFAULT_IGNORE_DIRS, out = new Set()) {
+  if (!existsSync(baseCwd)) return Array.from(out);
+
+  const paths = resolveTicketSystemPaths(baseCwd);
+  if (existsSync(paths.primary) || paths.legacy.length > 0) {
     out.add(baseCwd);
   }
 
   try {
-    const entries = readdirSync(baseCwd, { withFileTypes: true });
+    const entries = readdirSync(baseCwd, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
     for (const ent of entries) {
       if (!ent.isDirectory()) continue;
-      // Skip system or noisy directories based on ignoreDirs configuration
       if (ignoreDirs.includes(ent.name) || ent.name.startsWith(".deuk-agent")) continue;
-      discoverAllSubmodules(join(baseCwd, ent.name), ignoreDirs, out);
+      discoverAllWorkspaces(join(baseCwd, ent.name), ignoreDirs, out);
     }
-  } catch {
-    // Ignore permission errors on specific subfolders
+  } catch (err) {
+    if (process.env.DEBUG) console.warn(`[DEBUG] Failed to read directory ${baseCwd}:`, err);
   }
   return Array.from(out);
 }
+
+async function probeMcpUrl(url) {
+  const methods = ["HEAD", "GET"];
+
+  for (const method of methods) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1000);
+    try {
+      const res = await fetch(url, { method, signal: controller.signal });
+      if (res.body?.cancel) await res.body.cancel().catch(() => {});
+      if (res.ok || res.status === 405) return true;
+    } catch (err) {
+      if (process.env.DEBUG) console.warn(`[DEBUG] SSE ${method} ping failed for ${url}:`, err);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if the deuk-agent-context MCP server is active for the given workspace.
+ * Detects .mcp.json, .cursor/mcp.json, or .vscode/mcp.json and pings SSE servers if applicable.
+ */
+export async function isMcpActive(cwd) {
+  const mcpPaths = [
+    join(cwd, ".mcp.json"),
+    join(cwd, ".cursor", "mcp.json"),
+    join(cwd, ".vscode", "mcp.json")
+  ];
+  for (const p of mcpPaths) {
+    if (existsSync(p)) {
+      try {
+        const config = JSON.parse(readFileSync(p, "utf8"));
+        const servers = config.mcpServers || config.servers || {};
+        const deuk = servers["deuk-agent-context"] || servers["deuk_agent_context"];
+        if (deuk) {
+          if (deuk.command) return true; // Stdio is managed by IDE
+          if (deuk.url) {
+            return await probeMcpUrl(deuk.url);
+          }
+        }
+      } catch (err) {
+        if (process.env.DEBUG) console.warn(`[DEBUG] Failed to parse MCP config ${p}: ${err.message}`);
+        continue;
+      }
+    }
+  }
+  return false;
+}