igel-qe-core 1.0.16 → 1.0.20

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { spawn, spawnSync, execSync } from "child_process";
-import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { setupPlatform } from "./platform.js";
@@ -220,34 +220,63 @@ function listFrameworkContextFiles(workspaceRoot) {
     }
     return Array.from(new Set(found)).sort();
 }
-function isCopilotCliAvailable() {
-    // Use a short timeout so this never blocks if copilot hangs on startup.
-    const check = spawnSync("copilot", ["--version"], {
+function detectCopilotVariant() {
+    // Try `gh copilot --version` first (modern, official gh extension)
+    const ghCheck = spawnSync("gh", ["copilot", "--version"], {
         encoding: "utf-8",
         shell: process.platform === "win32",
-        timeout: 10_000,
+        timeout: 8_000,
     });
-    return check.status === 0 && !check.error;
+    if (ghCheck.status === 0 && !ghCheck.error)
+        return "gh";
+    // Fallback: legacy standalone `copilot` binary
+    const legacyCheck = spawnSync("copilot", ["--version"], {
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+        timeout: 8_000,
+    });
+    if (legacyCheck.status === 0 && !legacyCheck.error)
+        return "legacy";
+    return null;
+}
+function isCopilotCliAvailable() {
+    return detectCopilotVariant() !== null;
 }
 function isCopilotAuthenticated() {
-    // Use a lightweight auth-status check instead of spawning a full agent session.
-    // "copilot auth status" exits 0 when authenticated, non-zero otherwise.
-    // Fallback: if the sub-command doesn't exist, treat as unauthenticated.
+    const variant = detectCopilotVariant();
+    if (!variant)
+        return false;
+    if (variant === "gh") {
+        // `gh auth status` exits 0 when authenticated
+        const probe = spawnSync("gh", ["auth", "status"], {
+            encoding: "utf-8",
+            shell: process.platform === "win32",
+            timeout: 10_000,
+        });
+        return probe.status === 0 && !probe.error;
+    }
+    // Legacy variant — try `copilot auth status`
     const probe = spawnSync("copilot", ["auth", "status"], {
         encoding: "utf-8",
         shell: process.platform === "win32",
-        timeout: 10_000, // 10 s max — simple status call should be instant
+        timeout: 10_000,
     });
     return probe.status === 0 && !probe.error;
 }
 function ensureCopilotLogin(workspaceRoot) {
-    if (!isCopilotCliAvailable())
+    const variant = detectCopilotVariant();
+    if (!variant)
         return false;
     if (isCopilotAuthenticated())
         return true;
     console.log(chalk.yellow("   ⚠ GitHub Copilot CLI is not authenticated."));
     console.log(chalk.yellow("   → Please complete Copilot login to continue context enrichment."));
-    const login = spawnSync("copilot", ["login"], { stdio: "inherit", encoding: "utf-8", shell: process.platform === "win32" });
+    const loginCmd = variant === "gh" ? ["gh", "auth", "login"] : ["copilot", "login"];
+    const login = spawnSync(loginCmd[0], loginCmd.slice(1), {
+        stdio: "inherit",
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+    });
     if (login.status !== 0)
         return false;
     return isCopilotAuthenticated();
@@ -255,6 +284,59 @@ function ensureCopilotLogin(workspaceRoot) {
 // Maximum number of context.md files to enrich per init run.
 // Prevents extremely long waits on repos with many folders.
 const MAX_ENRICHMENT_FILES = 15;
+/**
+ * Attempt to enrich a single context.md file using `gh copilot suggest`.
+ * Returns the enriched text, or null on failure/empty response.
+ */
+function tryGhCopilotSuggest(workspaceRoot, relPath, currentContent) {
+    const prompt = [
+        `You are enriching a context.md file for an automation test framework.`,
+        `The file is located at: ${relPath} (relative to the workspace root).`,
+        ``,
+        `Current content:`,
+        `\`\`\`markdown`,
+        currentContent,
+        `\`\`\``,
+        ``,
+        `Rewrite the content above to be concrete, human-understandable, and LLM-ready.`,
+        `Requirements:`,
+        `- Keep the same heading structure (# Context, ## Purpose, ## Key Assets, ## Conventions, ## Risks and Dependencies).`,
+        `- Replace placeholder text with specific details inferred from the folder path and framework context.`,
+        `- Be concise but informative. Each section: 2–5 bullet points or short sentences.`,
+        `- Output ONLY the improved markdown. Do NOT add commentary, code fences, or extra text around it.`,
+    ].join("\n");
+    const variant = detectCopilotVariant();
+    let result;
+    if (variant === "gh") {
+        // Modern: `gh copilot suggest -t shell "<prompt>"`
+        // We use --no-color so output can be parsed cleanly.
+        result = spawnSync("gh", ["copilot", "suggest", "-t", "shell", "--", prompt], {
+            cwd: workspaceRoot,
+            encoding: "utf-8",
+            shell: process.platform === "win32",
+            timeout: 120_000,
+            input: "\n", // auto-accept any interactive prompt
+            maxBuffer: 4 * 1024 * 1024,
+        });
+    }
+    else if (variant === "legacy") {
+        // Legacy @githubnext/github-copilot-cli binary
+        result = spawnSync("copilot", ["-C", workspaceRoot, "-p", prompt, "--no-color", "-s"], {
+            encoding: "utf-8",
+            shell: process.platform === "win32",
+            timeout: 120_000,
+            input: "",
+            maxBuffer: 4 * 1024 * 1024,
+        });
+    }
+    else {
+        return null;
+    }
+    if (!result || result.status !== 0 || result.error)
+        return null;
+    const text = (result.stdout || "").trim();
+    return text.length > 50 ? text : null;
+}
 function enrichWithCopilotCli(workspaceRoot, contextFiles) {
     let updated = 0;
     let failed = 0;
@@ -263,38 +345,37 @@ function enrichWithCopilotCli(workspaceRoot, contextFiles) {
     const total = filesToProcess.length;
     for (let i = 0; i < filesToProcess.length; i++) {
         const absPath = filesToProcess[i];
-        const relPath = absPath.replace(`${workspaceRoot}/`, "").replace(`${workspaceRoot}\\`, "");
-        // Show per-file progress so the user knows work is happening.
+        // Normalise to forward slashes so the prompt is readable on all platforms.
+        const relPath = absPath
+            .replace(`${workspaceRoot}\\`, "")
+            .replace(`${workspaceRoot}/`, "")
+            .replace(/\\/g, "/");
         process.stdout.write(`   [${i + 1}/${total}] Enriching ${relPath}…`);
-        const prompt = [
-            `Update the markdown file at path '${relPath}' in place.`,
-            "Goal: make it both human-understandable and LLM-ready for automation framework reasoning.",
-            "Requirements:",
-            "- Keep heading style consistent.",
-            "- Include: purpose, architecture role, key assets, dependencies, conventions, risks, and update guidance.",
-            "- Be concrete and repository-aware.",
-            "- Do not modify any file other than the target file.",
-            "- Preserve valid markdown.",
-        ].join("\n");
-        const result = spawnSync("copilot", [
-            "-C", workspaceRoot,
-            "-p", prompt,
-            "--allow-all-tools",
-            "--allow-all-paths",
-            "--no-color",
-            "-s",
-        ], {
-            encoding: "utf-8",
-            shell: process.platform === "win32",
-            timeout: 120_000, // 2 min per file — prevents indefinite hangs
-            input: "", // close stdin immediately
-        });
-        if (result.status === 0 && !result.error) {
-            process.stdout.write(" ✓\n");
-            updated += 1;
+        let currentContent = "";
+        try {
+            currentContent = readFileSync(absPath, "utf-8");
+        }
+        catch {
+            process.stdout.write(" ✗ (unreadable)\n");
+            failed += 1;
+            continue;
+        }
+        const enriched = tryGhCopilotSuggest(workspaceRoot, relPath, currentContent);
+        if (enriched) {
+            try {
+                writeFileSync(absPath, enriched, "utf-8");
+                process.stdout.write(" ✓\n");
+                updated += 1;
+            }
+            catch {
+                process.stdout.write(" ✗ (write failed)\n");
+                failed += 1;
+            }
         }
         else {
-            process.stdout.write(" ✗\n");
+            // Copilot returned empty/trivial output — not a hard failure.
+            // The Python AST enricher will handle these in the fallback pass.
+            process.stdout.write(" ✗ (empty response)\n");
             failed += 1;
         }
     }
@@ -463,21 +544,71 @@ program
             if (allContextFiles.length === 0) {
                 console.log(chalk.yellow("   ⚠ No context.md files found for Copilot enrichment"));
             }
-            else if (!isCopilotCliAvailable()) {
-                console.log(chalk.yellow("   ⚠ Copilot CLI not installed; skipping Copilot enrichment"));
-            }
-            else if (!ensureCopilotLogin(workspaceRoot)) {
-                console.log(chalk.yellow("   ⚠ Copilot login was not completed; skipping Copilot enrichment"));
-            }
             else {
                 const cap = Math.min(allContextFiles.length, MAX_ENRICHMENT_FILES);
                 if (allContextFiles.length > MAX_ENRICHMENT_FILES) {
                     console.log(chalk.gray(`   - ${allContextFiles.length} context files found; enriching first ${MAX_ENRICHMENT_FILES} (re-run to continue)`));
                 }
-                const run = enrichWithCopilotCli(workspaceRoot, allContextFiles);
-                console.log(chalk.green(`   ✓ Copilot updated ${run.updated}/${cap} context.md file(s)`));
-                if (run.failed > 0) {
-                    console.log(chalk.yellow(`   ⚠ Copilot failed to update ${run.failed} context.md file(s)`));
+                const copilotVariant = detectCopilotVariant();
+                let copilotUpdated = 0;
+                let copilotFailed = 0;
+                if (!copilotVariant) {
+                    console.log(chalk.gray("   - GitHub Copilot CLI not found; using Python AST enricher directly"));
+                }
+                else if (!ensureCopilotLogin(workspaceRoot)) {
+                    console.log(chalk.yellow("   ⚠ Copilot login was not completed; using Python AST enricher as fallback"));
+                }
+                else {
+                    // Primary strategy: Copilot CLI
+                    const run = enrichWithCopilotCli(workspaceRoot, allContextFiles);
+                    copilotUpdated = run.updated;
+                    copilotFailed = run.failed;
+                    if (copilotUpdated > 0) {
+                        console.log(chalk.green(`   ✓ Copilot updated ${copilotUpdated}/${cap} context.md file(s)`));
+                    }
+                }
+                // Fallback / supplementary: Python AST enricher.
+                // Runs when Copilot is unavailable OR Copilot returned empty responses.
+                // The Python enricher does not require Copilot — it uses AST analysis
+                // and the Azure OpenAI key already configured in the project.
+                const needsFallback = copilotFailed > 0 || copilotUpdated === 0;
+                if (needsFallback) {
+                    const skippedFiles = allContextFiles
+                        .slice(0, MAX_ENRICHMENT_FILES)
+                        .filter((f) => {
+                        // Only send files that Copilot did NOT update (i.e. the ones that failed).
+                        // We approximate this as: all files when copilotUpdated=0,
+                        // or the trailing copilotFailed files otherwise.
+                        return true; // enrich_framework_context is idempotent — safe to re-enrich
+                    });
+                    if (skippedFiles.length > 0) {
+                        if (copilotVariant) {
+                            console.log(chalk.gray(`   - Falling back to Python AST enricher for ${copilotFailed} file(s) Copilot missed…`));
+                        }
+                        else {
+                            console.log(chalk.gray(`   - Enriching ${Math.min(skippedFiles.length, MAX_ENRICHMENT_FILES)} context.md file(s) via Python AST enricher…`));
+                        }
+                        try {
+                            const enrichResult = await runWorkflow("enrich_framework_context", {
+                                repo_path: workspaceRoot,
+                                context_paths: skippedFiles.slice(0, MAX_ENRICHMENT_FILES),
+                            });
+                            const pyUpdated = Number(enrichResult.updated ?? 0);
+                            const pyFailed = Number(enrichResult.failed ?? 0);
+                            if (pyUpdated > 0) {
+                                console.log(chalk.green(`   ✓ Python AST enricher updated ${pyUpdated} context.md file(s)`));
+                            }
+                            if (pyFailed > 0) {
+                                console.log(chalk.yellow(`   ⚠ Python AST enricher could not update ${pyFailed} file(s) (DB may be offline — files are still readable)`));
+                            }
+                        }
+                        catch (pyErr) {
+                            // Python enricher failed (likely DB offline) — not fatal.
+                            // Context files still have the scaffolded template content.
+                            console.log(chalk.yellow(`   ⚠ Python enricher skipped: ${pyErr instanceof Error ? pyErr.message : String(pyErr)}`));
+                            console.log(chalk.gray("   - Context files contain template scaffolding; enrichment can be re-run after DB is configured."));
+                        }
+                    }
                 }
             }
         }
@@ -660,6 +791,22 @@ program
             console.log(JSON.stringify(result, null, 2));
         }
         else {
+            // DB-offline / degraded state — return a helpful message rather than nothing
+            if (result.db_offline || result.error) {
+                const msg = String(result.message || result.error || "Unknown error");
+                if (result.db_offline) {
+                    console.log(chalk.yellow("\n⚠ Database not reachable"));
+                    console.log(chalk.gray(`  ${msg}`));
+                    console.log(chalk.gray("\n  Checklist:"));
+                    console.log(chalk.gray("   1. Ensure PostgreSQL is running on 127.0.0.1:5432"));
+                    console.log(chalk.gray("   2. Set DB_PASSWORD (and optionally DB_USER, DB_NAME) in your .env or shell"));
+                    console.log(chalk.gray("   3. Re-run: igel-qe init"));
+                }
+                else {
+                    console.log(chalk.yellow(`\n⚠ Status unavailable: ${msg}`));
+                }
+                return;
+            }
             const state = result;
             console.log(chalk.bold("\nProject State"));
             const ps = state.project_state;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igel-qe-core",
-  "version": "1.0.16",
+  "version": "1.0.20",
   "description": "IGEL QE Developer Experience Layer (CLI & MCP)",
   "type": "module",
   "publishConfig": {

package/src/cli/index.ts

@@ -3,7 +3,7 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { spawn, spawnSync, execSync } from "child_process";
-import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { setupPlatform } from "./platform.js";
@@ -231,40 +231,75 @@ function listFrameworkContextFiles(workspaceRoot: string): string[] {
   return Array.from(new Set(found)).sort();
 }
 
-function isCopilotCliAvailable(): boolean {
-  // Use a short timeout so this never blocks if copilot hangs on startup.
-  const check = spawnSync("copilot", ["--version"], {
+// ── Copilot CLI detection ──────────────────────────────────────────────────────
+// Supports two CLI variants:
+//   1. Modern:  `gh copilot suggest "<prompt>"` (gh extension, current standard)
+//   2. Legacy:  `copilot --version`  (@githubnext/github-copilot-cli, deprecated)
+// Detection tries `gh copilot` first; falls back to bare `copilot` binary.
+
+type CopilotVariant = "gh" | "legacy" | null;
+
+function detectCopilotVariant(): CopilotVariant {
+  // Try `gh copilot --version` first (modern, official gh extension)
+  const ghCheck = spawnSync("gh", ["copilot", "--version"], {
     encoding: "utf-8",
     shell: process.platform === "win32",
-    timeout: 10_000,
+    timeout: 8_000,
   });
-  return check.status === 0 && !check.error;
+  if (ghCheck.status === 0 && !ghCheck.error) return "gh";
+
+  // Fallback: legacy standalone `copilot` binary
+  const legacyCheck = spawnSync("copilot", ["--version"], {
+    encoding: "utf-8",
+    shell: process.platform === "win32",
+    timeout: 8_000,
+  });
+  if (legacyCheck.status === 0 && !legacyCheck.error) return "legacy";
+
+  return null;
+}
+
+function isCopilotCliAvailable(): boolean {
+  return detectCopilotVariant() !== null;
 }
 
 function isCopilotAuthenticated(): boolean {
-  // Use a lightweight auth-status check instead of spawning a full agent session.
-  // "copilot auth status" exits 0 when authenticated, non-zero otherwise.
-  // Fallback: if the sub-command doesn't exist, treat as unauthenticated.
-  const probe = spawnSync(
-    "copilot",
-    ["auth", "status"],
-    {
+  const variant = detectCopilotVariant();
+  if (!variant) return false;
+
+  if (variant === "gh") {
+    // `gh auth status` exits 0 when authenticated
+    const probe = spawnSync("gh", ["auth", "status"], {
       encoding: "utf-8",
       shell: process.platform === "win32",
-      timeout: 10_000,   // 10 s max — simple status call should be instant
-    },
-  );
+      timeout: 10_000,
+    });
+    return probe.status === 0 && !probe.error;
+  }
+
+  // Legacy variant — try `copilot auth status`
+  const probe = spawnSync("copilot", ["auth", "status"], {
+    encoding: "utf-8",
+    shell: process.platform === "win32",
+    timeout: 10_000,
+  });
   return probe.status === 0 && !probe.error;
 }
 
 function ensureCopilotLogin(workspaceRoot: string): boolean {
-  if (!isCopilotCliAvailable()) return false;
+  const variant = detectCopilotVariant();
+  if (!variant) return false;
   if (isCopilotAuthenticated()) return true;
 
   console.log(chalk.yellow("   ⚠ GitHub Copilot CLI is not authenticated."));
   console.log(chalk.yellow("   → Please complete Copilot login to continue context enrichment."));
 
-  const login = spawnSync("copilot", ["login"], { stdio: "inherit", encoding: "utf-8", shell: process.platform === "win32" });
+  const loginCmd = variant === "gh" ? ["gh", "auth", "login"] : ["copilot", "login"];
+  const login = spawnSync(loginCmd[0], loginCmd.slice(1), {
+    stdio: "inherit",
+    encoding: "utf-8",
+    shell: process.platform === "win32",
+  });
   if (login.status !== 0) return false;
   return isCopilotAuthenticated();
 }
@@ -273,6 +308,72 @@ function ensureCopilotLogin(workspaceRoot: string): boolean {
 // Prevents extremely long waits on repos with many folders.
 const MAX_ENRICHMENT_FILES = 15;
 
+/**
+ * Attempt to enrich a single context.md file using `gh copilot suggest`.
+ * Returns the enriched text, or null on failure/empty response.
+ */
+function tryGhCopilotSuggest(
+  workspaceRoot: string,
+  relPath: string,
+  currentContent: string,
+): string | null {
+  const prompt = [
+    `You are enriching a context.md file for an automation test framework.`,
+    `The file is located at: ${relPath} (relative to the workspace root).`,
+    ``,
+    `Current content:`,
+    `\`\`\`markdown`,
+    currentContent,
+    `\`\`\``,
+    ``,
+    `Rewrite the content above to be concrete, human-understandable, and LLM-ready.`,
+    `Requirements:`,
+    `- Keep the same heading structure (# Context, ## Purpose, ## Key Assets, ## Conventions, ## Risks and Dependencies).`,
+    `- Replace placeholder text with specific details inferred from the folder path and framework context.`,
+    `- Be concise but informative. Each section: 2–5 bullet points or short sentences.`,
+    `- Output ONLY the improved markdown. Do NOT add commentary, code fences, or extra text around it.`,
+  ].join("\n");
+
+  const variant = detectCopilotVariant();
+
+  let result;
+  if (variant === "gh") {
+    // Modern: `gh copilot suggest -t shell "<prompt>"`
+    // We use --no-color so output can be parsed cleanly.
+    result = spawnSync(
+      "gh",
+      ["copilot", "suggest", "-t", "shell", "--", prompt],
+      {
+        cwd: workspaceRoot,
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+        timeout: 120_000,
+        input: "\n",           // auto-accept any interactive prompt
+        maxBuffer: 4 * 1024 * 1024,
+      },
+    );
+  } else if (variant === "legacy") {
+    // Legacy @githubnext/github-copilot-cli binary
+    result = spawnSync(
+      "copilot",
+      ["-C", workspaceRoot, "-p", prompt, "--no-color", "-s"],
+      {
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+        timeout: 120_000,
+        input: "",
+        maxBuffer: 4 * 1024 * 1024,
+      },
+    );
+  } else {
+    return null;
+  }
+
+  if (!result || result.status !== 0 || result.error) return null;
+  const text = (result.stdout || "").trim();
+  return text.length > 50 ? text : null;
+}
+
 function enrichWithCopilotCli(
   workspaceRoot: string,
   contextFiles: string[],
@@ -286,45 +387,37 @@ function enrichWithCopilotCli(
 
   for (let i = 0; i < filesToProcess.length; i++) {
     const absPath = filesToProcess[i];
-    const relPath = absPath.replace(`${workspaceRoot}/`, "").replace(`${workspaceRoot}\\`, "");
+    // Normalise to forward slashes so the prompt is readable on all platforms.
+    const relPath = absPath
+      .replace(`${workspaceRoot}\\`, "")
+      .replace(`${workspaceRoot}/`, "")
+      .replace(/\\/g, "/");
 
-    // Show per-file progress so the user knows work is happening.
     process.stdout.write(`   [${i + 1}/${total}] Enriching ${relPath}…`);
 
-    const prompt = [
-      `Update the markdown file at path '${relPath}' in place.`,
-      "Goal: make it both human-understandable and LLM-ready for automation framework reasoning.",
-      "Requirements:",
-      "- Keep heading style consistent.",
-      "- Include: purpose, architecture role, key assets, dependencies, conventions, risks, and update guidance.",
-      "- Be concrete and repository-aware.",
-      "- Do not modify any file other than the target file.",
-      "- Preserve valid markdown.",
-    ].join("\n");
-
-    const result = spawnSync(
-      "copilot",
-      [
-        "-C", workspaceRoot,
-        "-p", prompt,
-        "--allow-all-tools",
-        "--allow-all-paths",
-        "--no-color",
-        "-s",
-      ],
-      {
-        encoding: "utf-8",
-        shell: process.platform === "win32",
-        timeout: 120_000,  // 2 min per file — prevents indefinite hangs
-        input: "",         // close stdin immediately
-      },
-    );
+    let currentContent = "";
+    try {
+      currentContent = readFileSync(absPath, "utf-8");
+    } catch {
+      process.stdout.write(" ✗ (unreadable)\n");
+      failed += 1;
+      continue;
+    }
 
-    if (result.status === 0 && !result.error) {
-      process.stdout.write(" ✓\n");
-      updated += 1;
+    const enriched = tryGhCopilotSuggest(workspaceRoot, relPath, currentContent);
+    if (enriched) {
+      try {
+        writeFileSync(absPath, enriched, "utf-8");
+        process.stdout.write(" ✓\n");
+        updated += 1;
+      } catch {
+        process.stdout.write(" ✗ (write failed)\n");
+        failed += 1;
+      }
     } else {
-      process.stdout.write(" ✗\n");
+      // Copilot returned empty/trivial output — not a hard failure.
+      // The Python AST enricher will handle these in the fallback pass.
+      process.stdout.write(" ✗ (empty response)\n");
       failed += 1;
     }
   }
@@ -499,19 +592,70 @@ program
         const allContextFiles = listFrameworkContextFiles(workspaceRoot);
         if (allContextFiles.length === 0) {
           console.log(chalk.yellow("   ⚠ No context.md files found for Copilot enrichment"));
-        } else if (!isCopilotCliAvailable()) {
-          console.log(chalk.yellow("   ⚠ Copilot CLI not installed; skipping Copilot enrichment"));
-        } else if (!ensureCopilotLogin(workspaceRoot)) {
-          console.log(chalk.yellow("   ⚠ Copilot login was not completed; skipping Copilot enrichment"));
         } else {
           const cap = Math.min(allContextFiles.length, MAX_ENRICHMENT_FILES);
           if (allContextFiles.length > MAX_ENRICHMENT_FILES) {
             console.log(chalk.gray(`   - ${allContextFiles.length} context files found; enriching first ${MAX_ENRICHMENT_FILES} (re-run to continue)`));
           }
-          const run = enrichWithCopilotCli(workspaceRoot, allContextFiles);
-          console.log(chalk.green(`   ✓ Copilot updated ${run.updated}/${cap} context.md file(s)`));
-          if (run.failed > 0) {
-            console.log(chalk.yellow(`   ⚠ Copilot failed to update ${run.failed} context.md file(s)`));
+
+          const copilotVariant = detectCopilotVariant();
+          let copilotUpdated = 0;
+          let copilotFailed = 0;
+
+          if (!copilotVariant) {
+            console.log(chalk.gray("   - GitHub Copilot CLI not found; using Python AST enricher directly"));
+          } else if (!ensureCopilotLogin(workspaceRoot)) {
+            console.log(chalk.yellow("   ⚠ Copilot login was not completed; using Python AST enricher as fallback"));
+          } else {
+            // Primary strategy: Copilot CLI
+            const run = enrichWithCopilotCli(workspaceRoot, allContextFiles);
+            copilotUpdated = run.updated;
+            copilotFailed = run.failed;
+            if (copilotUpdated > 0) {
+              console.log(chalk.green(`   ✓ Copilot updated ${copilotUpdated}/${cap} context.md file(s)`));
+            }
+          }
+
+          // Fallback / supplementary: Python AST enricher.
+          // Runs when Copilot is unavailable OR Copilot returned empty responses.
+          // The Python enricher does not require Copilot — it uses AST analysis
+          // and the Azure OpenAI key already configured in the project.
+          const needsFallback = copilotFailed > 0 || copilotUpdated === 0;
+          if (needsFallback) {
+            const skippedFiles = allContextFiles
+              .slice(0, MAX_ENRICHMENT_FILES)
+              .filter((f) => {
+                // Only send files that Copilot did NOT update (i.e. the ones that failed).
+                // We approximate this as: all files when copilotUpdated=0,
+                // or the trailing copilotFailed files otherwise.
+                return true; // enrich_framework_context is idempotent — safe to re-enrich
+              });
+            if (skippedFiles.length > 0) {
+              if (copilotVariant) {
+                console.log(chalk.gray(`   - Falling back to Python AST enricher for ${copilotFailed} file(s) Copilot missed…`));
+              } else {
+                console.log(chalk.gray(`   - Enriching ${Math.min(skippedFiles.length, MAX_ENRICHMENT_FILES)} context.md file(s) via Python AST enricher…`));
+              }
+              try {
+                const enrichResult = await runWorkflow("enrich_framework_context", {
+                  repo_path: workspaceRoot,
+                  context_paths: skippedFiles.slice(0, MAX_ENRICHMENT_FILES),
+                }) as Record<string, unknown>;
+                const pyUpdated = Number(enrichResult.updated ?? 0);
+                const pyFailed  = Number(enrichResult.failed  ?? 0);
+                if (pyUpdated > 0) {
+                  console.log(chalk.green(`   ✓ Python AST enricher updated ${pyUpdated} context.md file(s)`));
+                }
+                if (pyFailed > 0) {
+                  console.log(chalk.yellow(`   ⚠ Python AST enricher could not update ${pyFailed} file(s) (DB may be offline — files are still readable)`));
+                }
+              } catch (pyErr: unknown) {
+                // Python enricher failed (likely DB offline) — not fatal.
+                // Context files still have the scaffolded template content.
+                console.log(chalk.yellow(`   ⚠ Python enricher skipped: ${pyErr instanceof Error ? pyErr.message : String(pyErr)}`) );
+                console.log(chalk.gray("   - Context files contain template scaffolding; enrichment can be re-run after DB is configured."));
+              }
+            }
           }
         }
       } catch (e: unknown) {
@@ -697,6 +841,22 @@ program
       if (options.json) {
         console.log(JSON.stringify(result, null, 2));
       } else {
+        // DB-offline / degraded state — return a helpful message rather than nothing
+        if (result.db_offline || result.error) {
+          const msg = String(result.message || result.error || "Unknown error");
+          if (result.db_offline) {
+            console.log(chalk.yellow("\n⚠ Database not reachable"));
+            console.log(chalk.gray(`  ${msg}`));
+            console.log(chalk.gray("\n  Checklist:"));
+            console.log(chalk.gray("   1. Ensure PostgreSQL is running on 127.0.0.1:5432"));
+            console.log(chalk.gray("   2. Set DB_PASSWORD (and optionally DB_USER, DB_NAME) in your .env or shell"));
+            console.log(chalk.gray("   3. Re-run: igel-qe init"));
+          } else {
+            console.log(chalk.yellow(`\n⚠ Status unavailable: ${msg}`));
+          }
+          return;
+        }
+
         const state = (result as Record<string, unknown>);
         console.log(chalk.bold("\nProject State"));
         const ps = state.project_state as Record<string, number> | undefined;

package/src/cli/workflow_cli.py

@@ -27,18 +27,32 @@ _PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
 if str(_PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(_PROJECT_ROOT))
 
-from src.db.igel_schema import ensure_igel_tables
-from src.connectors.jira_connector import JiraConnector
-from src.agents.workflow_engine import WorkflowEngine
-from src.intelligence.diff_analyzer import analyze_diff_scope
-from src.intelligence.routing_engine import RouteInputs, compute_weighted_score, classify_route
-from src.agents.framework_analyzer_agent import FrameworkAnalyzerAgent
-from src.agents.orchestrator.orchestrator import Orchestrator
-from src.agents.internal.approval_manager import ApprovalError
-from src.config import cfg
-from src.project.context_projection_builder import ContextProjectionBuilder
-from src.project.context_requirement_sync import sync_requirement_context
-from src.project.context_enricher import enrich_context_files
+try:
+    from src.db.igel_schema import ensure_igel_tables
+    from src.connectors.jira_connector import JiraConnector
+    from src.agents.workflow_engine import WorkflowEngine
+    from src.intelligence.diff_analyzer import analyze_diff_scope
+    from src.intelligence.routing_engine import RouteInputs, compute_weighted_score, classify_route
+    from src.agents.framework_analyzer_agent import FrameworkAnalyzerAgent
+    from src.agents.orchestrator.orchestrator import Orchestrator
+    from src.agents.internal.approval_manager import ApprovalError
+    from src.config import cfg
+    from src.project.context_projection_builder import ContextProjectionBuilder
+    from src.project.context_requirement_sync import sync_requirement_context
+    from src.project.context_enricher import enrich_context_files
+    _DEPS_AVAILABLE = True
+    _DEPS_ERROR: str | None = None
+except ImportError as _ie:
+    _DEPS_AVAILABLE = False
+    _DEPS_ERROR = (
+        f"Missing Python dependency: {_ie}.\n"
+        "Run: igel-qe init --with-copilot  to install required packages."
+    )
+    # Define stubs so references below don't cause NameErrors
+    ensure_igel_tables = JiraConnector = WorkflowEngine = None  # type: ignore[assignment,misc]
+    analyze_diff_scope = RouteInputs = compute_weighted_score = classify_route = None  # type: ignore[assignment]
+    FrameworkAnalyzerAgent = Orchestrator = ApprovalError = cfg = None  # type: ignore[assignment,misc]
+    ContextProjectionBuilder = sync_requirement_context = enrich_context_files = None  # type: ignore[assignment]
 
 logging.basicConfig(level=logging.ERROR)  # Only output strict JSON to stdout
 
@@ -99,8 +113,39 @@ def main():
     except json.JSONDecodeError:
         _err("Invalid JSON args")
 
+    # ── Dependency guard ───────────────────────────────────────────────────────
+    # If core Python packages (e.g. psycopg2) are missing, return a structured
+    # warning for init_check so the CLI can surface a helpful message rather
+    # than crashing with a raw traceback.
+    if not _DEPS_AVAILABLE:
+        if args.action in ("init_project", "init_check"):
+            print(json.dumps({
+                "status": "success",
+                "ready": False,
+                "required_failed": ["python_dependencies"],
+                "warnings": [],
+                "checks": {
+                    "python_dependencies": {
+                        "status": "error",
+                        "message": _DEPS_ERROR or "Required Python packages not installed. Run: igel-qe init --with-copilot",
+                    }
+                },
+            }))
+            sys.exit(0)
+        else:
+            _err(_DEPS_ERROR or "Required Python packages not installed. Run: igel-qe init --with-copilot")
+
     # ── DB init ────────────────────────────────────────────────────────────────
-    if args.action not in ("submit_feedback",):
+    # Skip for init_check / init_project: those actions run run_checks() which
+    # already tests DB connectivity and reports a structured "postgres: fail"
+    # result instead of a hard crash. Calling ensure_igel_tables() here first
+    # would cause a non-zero exit before run_checks() ever runs, swallowing
+    # the structured error output that the Node CLI depends on.
+    # Skip for get_project_status: it reads from DB internally and returns a
+    # graceful "db_offline" response on failure — no schema init needed.
+    # Also skip for submit_feedback which manages its own connection.
+    _DB_SKIP_ACTIONS = ("submit_feedback", "init_check", "init_project", "get_project_status")
+    if args.action not in _DB_SKIP_ACTIONS:
         try:
             ensure_igel_tables()
         except Exception as e:
@@ -770,7 +815,9 @@ def main():
             projection = _best_effort_project_context(repo_path)
 
             _ok({
-                "enriched_count": len(enriched),
+                "updated": len(enriched),           # TS reads this for progress display
+                "failed": 0,                          # AST enricher does not partially fail
+                "enriched_count": len(enriched),      # backward compat alias
                 "enriched": [
                     {
                         "path": r.path,
@@ -787,7 +834,14 @@ def main():
                 "context_projection": projection,
             })
         except Exception as e:
-            _err(str(e))
+            # Return a partial-success response so TS can show a warning instead of crashing.
+            # Common failure: DB offline (context files are still written to disk).
+            _ok({
+                "updated": 0,
+                "failed": -1,  # signals error condition to TS
+                "error": str(e),
+                "enriched_count": 0,
+            })
 
     # ── update_context_file ─────────────────────────────────────────────────
     # Accepts: {
@@ -932,9 +986,21 @@ def main():
             summary = rebuild_system_state_from_db(root)
             _ok(summary)
         except Exception as e:
-            _err(str(e))
+            # Return graceful degraded status so `igel-qe status` doesn't crash
+            # when DB is offline — users should still get a useful message.
+            err_msg = str(e)
+            db_offline = "password" in err_msg.lower() or "connection" in err_msg.lower() or "psycopg" in err_msg.lower()
+            _ok({
+                "db_offline": db_offline,
+                "error": err_msg,
+                "project_state": None,
+                "sync_state": None,
+                "message": (
+                    "Database is offline or not configured. "
+                    "Set DB_PASSWORD / DATABASE_URL in your environment and re-run igel-qe init."
+                ) if db_offline else err_msg,
+            })
 
 
 if __name__ == "__main__":
     main()
-

package/src/db/client.py

@@ -3,15 +3,31 @@ from __future__ import annotations
 import logging
 import os
 
-import psycopg2
-import psycopg2.pool
+try:
+    import psycopg2
+    import psycopg2.pool
+    _PSYCOPG2_AVAILABLE = True
+except ImportError:
+    psycopg2 = None  # type: ignore[assignment]
+    _PSYCOPG2_AVAILABLE = False
+
 from contextlib import contextmanager
 
 from src.config import cfg
 
 logger = logging.getLogger(__name__)
 
-_pool: psycopg2.pool.ThreadedConnectionPool | None = None
+_pool: "psycopg2.pool.ThreadedConnectionPool | None" = None
+
+
+def _require_psycopg2() -> None:
+    """Raise a clear error if psycopg2 is not installed."""
+    if not _PSYCOPG2_AVAILABLE:
+        raise ImportError(
+            "psycopg2 is not installed. Run: pip install psycopg2-binary\n"
+            "or re-run: igel-qe init --with-copilot  (which will retry the install)"
+        )
+
 
 
 def _pool_kwargs() -> dict:
@@ -32,6 +48,7 @@ def _pool_kwargs() -> dict:
 
 
 def init_pool(minconn: int = 2, maxconn: int = 10) -> None:
+    _require_psycopg2()
     global _pool
     if _pool is not None:
         return

package/src/deploy/requirements.txt

@@ -49,7 +49,8 @@ beautifulsoup4>=4.12.0
 lxml>=5.0.0
 duckduckgo-search>=6.0.0,<7.0.0; python_version < "3.9"
 firecrawl-py>=1.0.0
-playwright>=1.40.0,<1.49.0
+# playwright: no upper bound — crawl4ai>=0.4 requires playwright>=1.49
+playwright>=1.49.0
 crawl4ai>=0.4.0,<0.5.0; python_version >= "3.9"
 
 # REST API server (always-running service)