igel-qe-core 1.0.18 → 1.0.20

package/dist/cli/index.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,
+    });
+    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,
     });
-    return check.status === 0 && !check.error;
+    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;
@@ -268,71 +350,32 @@ function enrichWithCopilotCli(workspaceRoot, contextFiles) {
             .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}…`);
-        // Read the current (template) content so Copilot can see the structure.
         let currentContent = "";
         try {
             currentContent = readFileSync(absPath, "utf-8");
         }
         catch {
-            // If we can't read, skip this file.
             process.stdout.write(" ✗ (unreadable)\n");
             failed += 1;
             continue;
         }
-        // Build a prompt that asks Copilot to RETURN the improved markdown as plain
-        // text to stdout. We write the file ourselves so we know it was updated.
-        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 result = spawnSync("copilot", [
-            "-C", workspaceRoot,
-            "-p", prompt,
-            "--no-color",
-            "-s",
-        ], {
-            encoding: "utf-8",
-            shell: process.platform === "win32",
-            timeout: 120_000, // 2 min per file — prevents indefinite hangs
-            input: "", // close stdin immediately
-            maxBuffer: 4 * 1024 * 1024, // 4 MB stdout buffer
-        });
-        if (result.status === 0 && !result.error) {
-            const enriched = (result.stdout || "").trim();
-            if (enriched.length > 50) {
-                // Only write back if Copilot returned meaningful content (>50 chars).
-                try {
-                    writeFileSync(absPath, enriched, "utf-8");
-                    process.stdout.write(" ✓\n");
-                    updated += 1;
-                }
-                catch {
-                    process.stdout.write(" ✗ (write failed)\n");
-                    failed += 1;
-                }
+        const enriched = tryGhCopilotSuggest(workspaceRoot, relPath, currentContent);
+        if (enriched) {
+            try {
+                writeFileSync(absPath, enriched, "utf-8");
+                process.stdout.write(" ✓\n");
+                updated += 1;
             }
-            else {
-                // Copilot ran but returned empty/trivial output.
-                process.stdout.write(" ✗ (empty response)\n");
+            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;
         }
     }
@@ -501,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."));
+                        }
+                    }
                 }
             }
         }
@@ -698,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.18",
+  "version": "1.0.20",
   "description": "IGEL QE Developer Experience Layer (CLI & MCP)",
   "type": "module",
   "publishConfig": {

package/src/cli/index.ts

@@ -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,
+  });
+  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,
   });
-  return check.status === 0 && !check.error;
+  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[],
@@ -292,75 +393,31 @@ function enrichWithCopilotCli(
       .replace(`${workspaceRoot}/`, "")
       .replace(/\\/g, "/");
 
-    // Show per-file progress so the user knows work is happening.
     process.stdout.write(`   [${i + 1}/${total}] Enriching ${relPath}…`);
 
-    // Read the current (template) content so Copilot can see the structure.
     let currentContent = "";
     try {
       currentContent = readFileSync(absPath, "utf-8");
     } catch {
-      // If we can't read, skip this file.
       process.stdout.write(" ✗ (unreadable)\n");
       failed += 1;
       continue;
     }
 
-    // Build a prompt that asks Copilot to RETURN the improved markdown as plain
-    // text to stdout. We write the file ourselves so we know it was updated.
-    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 result = spawnSync(
-      "copilot",
-      [
-        "-C", workspaceRoot,
-        "-p", prompt,
-        "--no-color",
-        "-s",
-      ],
-      {
-        encoding: "utf-8",
-        shell: process.platform === "win32",
-        timeout: 120_000,  // 2 min per file — prevents indefinite hangs
-        input: "",         // close stdin immediately
-        maxBuffer: 4 * 1024 * 1024,  // 4 MB stdout buffer
-      },
-    );
-
-    if (result.status === 0 && !result.error) {
-      const enriched = (result.stdout || "").trim();
-      if (enriched.length > 50) {
-        // Only write back if Copilot returned meaningful content (>50 chars).
-        try {
-          writeFileSync(absPath, enriched, "utf-8");
-          process.stdout.write(" ✓\n");
-          updated += 1;
-        } catch {
-          process.stdout.write(" ✗ (write failed)\n");
-          failed += 1;
-        }
-      } else {
-        // Copilot ran but returned empty/trivial output.
-        process.stdout.write(" ✗ (empty response)\n");
+    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;
     }
   }
@@ -535,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) {
@@ -733,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

@@ -136,7 +136,16 @@ def main():
             _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:
@@ -806,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,
@@ -823,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: {
@@ -968,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()
-