x-readiness-mcp 0.3.0 → 0.5.1

package/tools/gitignore-helper.js

@@ -0,0 +1,88 @@
+// mcp/tools/gitignore-helper.js
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Ensures .xreadiness/ is ignored by git
+ * Tries .gitignore first, falls back to .git/info/exclude
+ */
+export async function ensureXReadinessIgnored(repoPath) {
+  const gitignorePath = path.join(repoPath, ".gitignore");
+  const gitExcludePath = path.join(repoPath, ".git", "info", "exclude");
+  const ignoreEntry = ".xreadiness/";
+
+  // Try to add to .gitignore
+  try {
+    let gitignoreContent = "";
+    try {
+      gitignoreContent = await fs.readFile(gitignorePath, "utf8");
+    } catch {
+      // File doesn't exist, will create it
+    }
+
+    // Check if already present
+    if (gitignoreContent.includes(ignoreEntry)) {
+      return {
+        status: "ALREADY_IGNORED",
+        method: ".gitignore",
+        message: ".xreadiness/ is already in .gitignore"
+      };
+    }
+
+    // Append to .gitignore
+    const newContent = gitignoreContent.trim()
+      ? `${gitignoreContent.trim()}\n\n# X-Readiness tool artifacts\n${ignoreEntry}\n`
+      : `# X-Readiness tool artifacts\n${ignoreEntry}\n`;
+    
+    await fs.writeFile(gitignorePath, newContent, "utf8");
+    
+    return {
+      status: "ADDED_TO_GITIGNORE",
+      method: ".gitignore",
+      path: gitignorePath,
+      message: `✅ Added ${ignoreEntry} to .gitignore`
+    };
+  } catch (gitignoreErr) {
+    // Fallback to .git/info/exclude
+    try {
+      let excludeContent = "";
+      try {
+        excludeContent = await fs.readFile(gitExcludePath, "utf8");
+      } catch {
+        // Create directory if needed
+        await fs.mkdir(path.dirname(gitExcludePath), { recursive: true });
+      }
+
+      // Check if already present
+      if (excludeContent.includes(ignoreEntry)) {
+        return {
+          status: "ALREADY_IGNORED",
+          method: ".git/info/exclude",
+          message: ".xreadiness/ is already in .git/info/exclude"
+        };
+      }
+
+      // Append to exclude
+      const newContent = excludeContent.trim()
+        ? `${excludeContent.trim()}\n\n# X-Readiness tool artifacts\n${ignoreEntry}\n`
+        : `# X-Readiness tool artifacts\n${ignoreEntry}\n`;
+      
+      await fs.writeFile(gitExcludePath, newContent, "utf8");
+      
+      return {
+        status: "ADDED_TO_EXCLUDE",
+        method: ".git/info/exclude",
+        path: gitExcludePath,
+        message: `✅ Added ${ignoreEntry} to .git/info/exclude (local ignore)`
+      };
+    } catch (excludeErr) {
+      return {
+        status: "FAILED",
+        error: `Could not add to .gitignore or .git/info/exclude`,
+        gitignore_error: gitignoreErr.message,
+        exclude_error: excludeErr.message,
+        message: "⚠️ Failed to auto-ignore .xreadiness/. Please add it manually to .gitignore"
+      };
+    }
+  }
+}

package/tools/planning.js

@@ -1,343 +1,130 @@
-// tools/planning.js
-// X-API Readiness Planning Tool (Deterministic / Offline)
-//
-// Contract:
-// - Input: { scope, format }
-// - Output: canonical JSON with `features[]` (stable IDs), optionally `markdown`.
-//
-// IMPORTANT: No network calls or HTML scraping. Everything is generated from
-// `templates/master_template.json` (sources/scopes/categories.expected_rules).
-
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const MASTER_TEMPLATE_PATH = path.join(__dirname, "..", "templates", "master_template.json");
-const MASTER_TEMPLATE_MD_PATH = path.join(__dirname, "..", "templates", "master_template.md");
-
-export async function generateChecklist(scope, format = "json") {
-  // Try to load JSON first, fallback to parsing MD if JSON doesn't exist
-  let template;
-  try {
-    template = loadMasterTemplate();
-  } catch (err) {
-    // If JSON doesn't exist, we'll use the MD version (for now just throw)
-    throw new Error(`Master template not found. Please ensure master_template.json exists: ${err.message}`);
-  }
-  const scopeKey = resolveScopeKey(scope, template);
-  const selectedSources = selectSourcesByScope(scopeKey, template);
-  const selectedCategories = selectCategoriesForSources(selectedSources, template);
-
-  const checklist = buildChecklistFromTemplate(scopeKey, selectedCategories, selectedSources, template);
-
-  if (format === "markdown") {
-    return {
-      ...checklist,
-      markdown: formatAsMarkdown(checklist)
-    };
-  }
-
-  if (format === "both") {
-    return {
-      ...checklist,
-      markdown: formatAsMarkdown(checklist)
-    };
-  }
-
-  return checklist;
-}
-
-export const planningTool = generateChecklist;
-
-function loadMasterTemplate() {
-  const raw = fs.readFileSync(MASTER_TEMPLATE_PATH, "utf8");
-  const template = JSON.parse(raw);
-
-  if (!template || typeof template !== "object") {
-    throw new Error("Invalid master template: not an object");
-  }
-  if (!Array.isArray(template.sources)) {
-    throw new Error("Invalid master template: missing 'sources[]'");
-  }
-  if (!template.scopes || typeof template.scopes !== "object") {
-    throw new Error("Invalid master template: missing 'scopes'");
-  }
-  if (!template.categories || typeof template.categories !== "object") {
-    throw new Error("Invalid master template: missing 'categories'");
-  }
-  return template;
-}
-
-function resolveScopeKey(scope, template) {
-  const scopeInput = (scope || "").toString().trim();
-  if (!scopeInput) return "x_api_readiness";
-
-  const directKey = scopeInput.toLowerCase();
-  if (template.scopes[directKey]) return directKey;
-
-  const normalized = directKey.replace(/[_-]/g, "");
-  for (const key of Object.keys(template.scopes)) {
-    if (key.replace(/[_-]/g, "") === normalized) return key;
-  }
-
-  return "x_api_readiness";
-}
-
-function selectSourcesByScope(scopeKey, template) {
-  const scopeConfig = template.scopes[scopeKey] || template.scopes.x_api_readiness;
-  const includePatterns = Array.isArray(scopeConfig?.include_ids) ? scopeConfig.include_ids : ["common-*", "rest-*"];
-  const excludePatterns = Array.isArray(scopeConfig?.exclude_ids) ? scopeConfig.exclude_ids : [];
-
-  return template.sources.filter((source) => {
-    if (!source || !source.id) return false;
-
-    const isIncluded = includePatterns.some((pattern) => matchIdPattern(source.id, pattern));
-    if (!isIncluded) return false;
-
-    const isExcluded = excludePatterns.some((pattern) => matchIdPattern(source.id, pattern));
-    if (isExcluded) return false;
-
-    return true;
-  });
-}
-
-function matchIdPattern(id, pattern) {
-  if (!pattern) return false;
-  if (pattern === "*") return true;
-  if (pattern.endsWith("*")) return id.startsWith(pattern.slice(0, -1));
-  if (pattern.startsWith("*")) return id.endsWith(pattern.slice(1));
-  return id === pattern;
-}
-
-function selectCategoriesForSources(selectedSources, template) {
-  const categories = template.categories;
-
-  // Build a reverse lookup: normalized guideline URL -> [{ categoryKey, category }]
-  const byUrl = new Map();
-  for (const [categoryKey, category] of Object.entries(categories)) {
-    const url = normalizeUrl(category?.guideline_url);
-    if (!url) continue;
-    const existing = byUrl.get(url) || [];
-    existing.push({ categoryKey, category });
-    byUrl.set(url, existing);
-  }
-
-  const selected = new Map();
-  for (const source of selectedSources) {
-    const url = normalizeUrl(source?.url);
-    if (!url) continue;
-    const matches = byUrl.get(url);
-    if (!matches || matches.length === 0) continue;
-
-    for (const match of matches) {
-      selected.set(match.categoryKey, match.category);
-    }
-  }
-
-  return selected;
-}
-
-function normalizeUrl(url) {
-  if (!url || typeof url !== "string") return null;
-  try {
-    const parsed = new URL(url);
-    parsed.hash = "";
-    // Some URLs might differ only by trailing slash
-    const normalized = parsed.toString().replace(/\/$/, "");
-    return normalized;
-  } catch {
-    return url.replace(/#.*$/, "").replace(/\/$/, "");
-  }
-}
-
-function buildChecklistFromTemplate(scopeKey, selectedCategoriesMap, selectedSources, template) {
-  const generatedAt = new Date().toISOString();
-  const checklistId = `xreadiness:${template.version || "0"}:${scopeKey}`;
-
-  const selectedCategories = Array.from(selectedCategoriesMap.entries())
-    .map(([categoryKey, category]) => ({ categoryKey, category }))
-    .sort((a, b) => a.categoryKey.localeCompare(b.categoryKey));
-
-  const features = selectedCategories
-    .map(({ categoryKey, category }) => buildFeature(categoryKey, category))
-    .filter((f) => f.rules.length > 0);
-
-  // Derived flattened rules for execution tool compatibility
-  const rules = [];
-  for (const feature of features) {
-    for (const rule of feature.rules) {
-      rules.push({
-        ruleId: rule.rule_id,
-        ruleName: rule.rule_name,
-        category: feature.category_key,
-        categoryKey: feature.category_key,
-        normative: rule.normative,
-        severity: rule.severity,
-        referenceUrl: rule.reference_url
-      });
+// mcp/tools/planning.js
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { generateChecklist } from "./template-parser.js";
+import { ensureXReadinessIgnored } from "./gitignore-helper.js";
+
+const PLAN_DIR_NAME = [".xreadiness", "plan"];
+
+function planDir(repoPath) {
+  return path.resolve(repoPath, ...PLAN_DIR_NAME);
+}
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+/**
+ * Generate plan markdown with high-level checklist
+ */
+function toPlanMarkdown({ planId, repoPath, scope, developerPrompt, checklist }) {
+  const totalRules = checklist.total_rules;
+
+  let md = `# X-Readiness Plan\n\n`;
+  md += `**Generated:** ${new Date().toISOString()}\n\n`;
+  md += `- **Plan ID:** ${planId}\n`;
+  md += `- **Repository Path:** ${repoPath}\n`;
+  md += `- **Scope:** ${scope}\n`;
+  md += `- **Scope Description:** ${checklist.scope_description}\n`;
+  md += `- **Developer Prompt:** ${developerPrompt}\n`;
+  md += `- **Total Rules Selected:** ${totalRules}\n`;
+  md += `- **Template Version:** ${checklist.template_version}\n\n`;
+
+  md += `---\n\n`;
+  md += `## Reference URLs\n\n`;
+  md += `- Common Guidelines: ${checklist.reference_urls.common}\n`;
+  md += `- REST Guidelines: ${checklist.reference_urls.rest}\n\n`;
+
+  md += `---\n\n`;
+  md += `## High-Level Checklist\n\n`;
+  md += `This plan will check the following categories and rules:\n\n`;
+
+  for (const category of checklist.categories) {
+    md += `### ${category.name} (Priority: ${category.priority})\n\n`;
+    md += `**Guideline:** [${category.name}](${category.guideline_url})\n\n`;
+    md += `**Rules to check:**\n\n`;
+    
+    for (const rule of category.rules) {
+      md += `- [ ] **${rule.rule_id}** — ${rule.rule_name}\n`;
     }
+    md += `\n`;
   }
 
-  const summary = computeSummary(features);
-
-  return {
-    checklist_id: checklistId,
-    scope: scopeKey,
-    generated_at: generatedAt,
-    template_version: template.version || null,
-    template_last_updated: template.last_updated || null,
-
-    // Canonical contract
-    features,
-
-    // Derived compatibility field for current execution tool
-    rules,
-
-    // Supporting metadata
-    sources_included: selectedSources.map((s) => ({
-      id: s.id,
-      area: s.area,
-      name: s.name,
-      url: s.url,
-      priority: s.priority || null
-    })),
-    summary
+  md += `---\n\n`;
+  md += `## Next Steps\n\n`;
+  md += `1. **Review this plan** to ensure it covers the requirements you need\n`;
+  md += `2. **⚠️ IMPORTANT:** Do NOT proceed with execution automatically\n`;
+  md += `3. **When ready to execute**, explicitly reply: **"Yes, run execution"**\n`;
+  md += `4. **Execution will require your approval code** before scanning your source code\n`;
+  md += `5. **To execute**, call the \`execute\` tool with:\n`;
+  md += `   - \`repoPath\`: ${repoPath}\n`;
+  md += `   - \`planPath\`: (path to this plan's JSON file)\n\n`;
+  
+  return md;
+}
+
+/**
+ * Main planning tool - generates plan and asks for approval to execute
+ */
+export async function planTool({ repoPath, scope, developerPrompt, outputFormat = "markdown" }) {
+  // Ensure .xreadiness/ is in .gitignore
+  const gitignoreResult = await ensureXReadinessIgnored(repoPath);
+
+  // Generate checklist from template based on scope and developer prompt
+  const checklist = await generateChecklist(scope, developerPrompt);
+
+  // Create unique plan ID
+  const planId = `plan_${new Date().toISOString().replace(/[:.]/g, "-")}_${crypto.randomUUID().slice(0, 8)}`;
+  const dir = planDir(repoPath);
+  await ensureDir(dir);
+
+  const planJsonPath = path.join(dir, `${planId}.json`);
+  const planMdPath = path.join(dir, `${planId}.md`);
+
+  // Build plan object
+  const plan = {
+    plan_id: planId,
+    scope,
+    scope_description: checklist.scope_description,
+    developer_prompt: developerPrompt,
+    created_at: new Date().toISOString(),
+    template_version: checklist.template_version,
+    reference_urls: checklist.reference_urls,
+    categories: checklist.categories,
+    total_rules: checklist.total_rules
   };
-}
-
-function buildFeature(categoryKey, category) {
-  const featureId = category?.id || categoryKey.toLowerCase();
-  const featureName = category?.name || categoryKey;
-  const guidelineUrl = category?.guideline_url || null;
-  const priority = category?.priority || "medium";
 
-  const expectedRules = category?.expected_rules && typeof category.expected_rules === "object"
-    ? category.expected_rules
-    : {};
-
-  const rules = Object.entries(expectedRules)
-    .map(([ruleNumber, ruleName]) => {
-      const normative = deriveNormative(ruleName);
-      return {
-        rule_id: `${categoryKey}-${ruleNumber}`,
-        rule_number: ruleNumber,
-        rule_name: ruleName,
-        reference_url: guidelineUrl,
-        severity: priorityToSeverity(priority),
-        normative,
-        adoption_condition: null,
-        evidence_hints: buildEvidenceHints(category)
-      };
-    })
-    .sort((a, b) => compareRuleNumbers(a.rule_number, b.rule_number));
-
-  return {
-    feature_id: featureId,
-    feature_name: featureName,
-    feature_description: category?.description || null,
-    guideline_url: guidelineUrl,
-    priority,
-
-    // Helps execution tool routing (PAGINATION, SECURITY, ...)
-    category_key: categoryKey,
-
-    rules
-  };
-}
-
-function buildEvidenceHints(category) {
-  const hints = [];
-  if (Array.isArray(category?.applies_to)) hints.push(...category.applies_to);
-  if (Array.isArray(category?.keywords)) hints.push(...category.keywords);
-  return Array.from(new Set(hints.filter(Boolean).map((h) => h.toString())));
-}
-
-function priorityToSeverity(priority) {
-  const p = (priority || "medium").toString().toLowerCase();
-  if (p === "critical") return "critical";
-  if (p === "high") return "high";
-  if (p === "low") return "low";
-  return "medium";
-}
+  // Write plan to JSON
+  await fs.writeFile(planJsonPath, JSON.stringify(plan, null, 2), "utf8");
 
-function deriveNormative(text) {
-  const value = (text || "").toString();
-  if (/\bMUST NOT\b/i.test(value)) return "MUST NOT";
-  if (/\bSHOULD NOT\b/i.test(value)) return "SHOULD NOT";
-  if (/\bMUST\b/i.test(value)) return "MUST";
-  if (/\bSHOULD\b/i.test(value)) return "SHOULD";
-  if (/\bMAY\b/i.test(value)) return "MAY";
-  return null;
-}
-
-function compareRuleNumbers(a, b) {
-  const aParts = (a || "").toString().split(".").map((x) => Number(x));
-  const bParts = (b || "").toString().split(".").map((x) => Number(x));
-
-  const max = Math.max(aParts.length, bParts.length);
-  for (let i = 0; i < max; i++) {
-    const av = Number.isFinite(aParts[i]) ? aParts[i] : 0;
-    const bv = Number.isFinite(bParts[i]) ? bParts[i] : 0;
-    if (av !== bv) return av - bv;
+  // Write plan to Markdown
+  if (outputFormat === "markdown" || outputFormat === "both") {
+    const md = toPlanMarkdown({ planId, repoPath, scope, developerPrompt, checklist });
+    await fs.writeFile(planMdPath, md, "utf8");
   }
-  return 0;
-}
-
-function computeSummary(features) {
-  const summary = {
-    total_features: features.length,
-    total_rules: 0,
-    by_severity: { critical: 0, high: 0, medium: 0, low: 0 },
-    by_normative: { MUST: 0, SHOULD: 0, MAY: 0, "MUST NOT": 0, "SHOULD NOT": 0, UNKNOWN: 0 }
-  };
-
-  for (const feature of features) {
-    for (const rule of feature.rules) {
-      summary.total_rules++;
-      const sev = rule.severity || "medium";
-      if (summary.by_severity[sev] === undefined) summary.by_severity[sev] = 0;
-      summary.by_severity[sev]++;
-
-      const norm = rule.normative || "UNKNOWN";
-      if (summary.by_normative[norm] === undefined) summary.by_normative[norm] = 0;
-      summary.by_normative[norm]++;
-    }
-  }
-
-  return summary;
-}
-
-function formatAsMarkdown(checklist) {
-  const lines = [];
-  lines.push(`# X-API Readiness Checklist (${checklist.scope})`);
-  lines.push("");
-  lines.push(`Generated: ${checklist.generated_at}`);
-  if (checklist.template_version) lines.push(`Template: ${checklist.template_version}`);
-  lines.push("");
-
-  for (const feature of checklist.features) {
-    lines.push(`## ${feature.feature_name}`);
-    if (feature.guideline_url) lines.push(`Source: ${feature.guideline_url}`);
-    lines.push("");
 
-    for (const rule of feature.rules) {
-      const norm = rule.normative ? ` (${rule.normative})` : "";
-      lines.push(`- [ ] ${rule.rule_id}${norm}: ${rule.rule_name}`);
+  return {
+    status: "PLAN_GENERATED",
+    plan_id: planId,
+    plan_json_path: planJsonPath,
+    plan_md_path: planMdPath,
+    gitignore_status: gitignoreResult,
+    summary: {
+      scope,
+      scope_description: checklist.scope_description,
+      total_rules: checklist.total_rules,
+      categories_count: checklist.categories.length
+    },
+    message: `✅ Plan generated successfully!\n\n📄 Plan saved to:\n- JSON: ${planJsonPath}\n- Markdown: ${planMdPath}\n\n${gitignoreResult.message}\n\n📋 This plan includes ${checklist.total_rules} rules across ${checklist.categories.length} categories.\n\n⚠️ NEXT STEPS:\n1. Review the plan carefully\n2. When ready, explicitly reply: "Yes, run execution"\n3. Do NOT proceed with execution automatically\n4. Execution will require an approval code before scanning your source code`,
+    instruction: "⚠️ Reply 'Yes, run execution' to proceed. Do NOT run execution without explicit user approval.",
+    next_step: {
+      tool: "execute",
+      parameters: {
+        repoPath: repoPath,
+        planPath: planJsonPath
+      },
+      note: "⚠️ Execution requires approval code. Wait for user confirmation before calling this tool."
     }
-
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-// Backward compatibility for local test runner
-export function formatChecklistAsTable(checklist) {
-  return formatAsMarkdown(checklist);
+  };
 }
-
-// Default export (used by `mcp/test-planner-v2.js`)
-export default generateChecklist;