igel-qe-core 1.0.14 → 1.0.18

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";
@@ -229,49 +229,79 @@ function isCopilotCliAvailable() {
     });
     return check.status === 0 && !check.error;
 }
-function isCopilotAuthenticated(workspaceRoot) {
-    // A strict timeout prevents the init command from hanging forever when
-    // Copilot waits for interactive input or a network response.
-    const probe = spawnSync("copilot", ["-C", workspaceRoot, "-p", "Reply with exactly OK.", "--allow-all-tools", "--no-color", "-s"], {
+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 probe = spawnSync("copilot", ["auth", "status"], {
         encoding: "utf-8",
         shell: process.platform === "win32",
-        timeout: 30_000, // 30 s max — return false if Copilot doesn't answer
-        input: "", // close stdin immediately so it doesn't wait for user input
+        timeout: 10_000, // 10 s max — simple status call should be instant
     });
     return probe.status === 0 && !probe.error;
 }
 function ensureCopilotLogin(workspaceRoot) {
     if (!isCopilotCliAvailable())
         return false;
-    if (isCopilotAuthenticated(workspaceRoot))
+    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" });
     if (login.status !== 0)
         return false;
-    return isCopilotAuthenticated(workspaceRoot);
+    return isCopilotAuthenticated();
 }
+// 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;
 function enrichWithCopilotCli(workspaceRoot, contextFiles) {
     let updated = 0;
     let failed = 0;
-    for (const absPath of contextFiles) {
-        const relPath = absPath.replace(`${workspaceRoot}/`, "");
+    // Limit the number of files processed in one init run.
+    const filesToProcess = contextFiles.slice(0, MAX_ENRICHMENT_FILES);
+    const total = filesToProcess.length;
+    for (let i = 0; i < filesToProcess.length; i++) {
+        const absPath = filesToProcess[i];
+        // 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}…`);
+        // 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 = [
-            `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.",
+            `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,
-            "--allow-all-tools",
-            "--allow-all-paths",
             "--no-color",
             "-s",
         ], {
@@ -279,11 +309,30 @@ function enrichWithCopilotCli(workspaceRoot, contextFiles) {
             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) {
-            updated += 1;
+        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");
+                failed += 1;
+            }
         }
         else {
+            process.stdout.write(" ✗\n");
             failed += 1;
         }
     }
@@ -409,7 +458,9 @@ program
             // Wrap both the python path and requirements path in quotes so
             // Windows paths that contain spaces (e.g. "IGEL Automation July 2026")
             // are treated as a single argument by the shell.
-            execSync(`"${pyBin}" -m pip install -q -r "${reqPath}"`, {
+            // --prefer-binary: use pre-built wheels instead of compiling from source
+            // (avoids Rust/Cargo requirement for packages like tokenizers, crawl4ai)
+            execSync(`"${pyBin}" -m pip install -q --prefer-binary -r "${reqPath}"`, {
                 cwd: workspaceRoot, stdio: "inherit",
             });
             console.log(chalk.green("   ✓ Dependencies installed"));
@@ -436,29 +487,41 @@ program
     else {
         console.log(chalk.green("   ✓ Framework context files already up to date"));
     }
-    // Step 2d — Copilot CLI enrichment pass (asks login if needed), then DB sync.
+    // Step 3d — Copilot CLI enrichment pass.
+    // Only run when --with-copilot / --with-all is explicitly requested.
+    // Skipped silently on plain `igel-qe init` to avoid unexpected long waits.
+    const runEnrichment = options.withCopilot || options.withAll;
     console.log(chalk.yellow("3d. Enriching context via GitHub Copilot CLI…"));
-    try {
-        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 run = enrichWithCopilotCli(workspaceRoot, allContextFiles);
-            console.log(chalk.green(`   ✓ Copilot updated ${run.updated} context.md file(s)`));
-            if (run.failed > 0) {
-                console.log(chalk.yellow(`   ⚠ Copilot failed to update ${run.failed} context.md file(s)`));
+    if (!runEnrichment) {
+        console.log(chalk.gray("   - Skipped (pass --with-copilot to enable Copilot context enrichment)"));
+    }
+    else {
+        try {
+            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)`));
+                }
             }
         }
-    }
-    catch (e) {
-        console.log(chalk.yellow(`   ⚠ Copilot context enrichment skipped: ${e instanceof Error ? e.message : String(e)}`));
+        catch (e) {
+            console.log(chalk.yellow(`   ⚠ Copilot context enrichment skipped: ${e instanceof Error ? e.message : String(e)}`));
+        }
     }
     // Step 3 — write MCP config (default: Copilot when no explicit platform flags)
     console.log(chalk.yellow("4. Configuring MCP server…"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "igel-qe-core",
-  "version": "1.0.14",
+  "version": "1.0.18",
   "description": "IGEL QE Developer Experience Layer (CLI & MCP)",
   "type": "module",
   "publishConfig": {
@@ -16,6 +16,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepublishOnly": "tsc",
     "start:mcp": "node ./dist/mcp/server.js"
   },
   "dependencies": {

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";
@@ -241,17 +241,17 @@ function isCopilotCliAvailable(): boolean {
   return check.status === 0 && !check.error;
 }
 
-function isCopilotAuthenticated(workspaceRoot: string): boolean {
-  // A strict timeout prevents the init command from hanging forever when
-  // Copilot waits for interactive input or a network response.
+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",
-    ["-C", workspaceRoot, "-p", "Reply with exactly OK.", "--allow-all-tools", "--no-color", "-s"],
+    ["auth", "status"],
     {
       encoding: "utf-8",
       shell: process.platform === "win32",
-      timeout: 30_000,   // 30 s max — return false if Copilot doesn't answer
-      input: "",         // close stdin immediately so it doesn't wait for user input
+      timeout: 10_000,   // 10 s max — simple status call should be instant
     },
   );
   return probe.status === 0 && !probe.error;
@@ -259,31 +259,70 @@ function isCopilotAuthenticated(workspaceRoot: string): boolean {
 
 function ensureCopilotLogin(workspaceRoot: string): boolean {
   if (!isCopilotCliAvailable()) return false;
-  if (isCopilotAuthenticated(workspaceRoot)) return true;
+  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" });
   if (login.status !== 0) return false;
-  return isCopilotAuthenticated(workspaceRoot);
+  return isCopilotAuthenticated();
 }
 
-function enrichWithCopilotCli(workspaceRoot: string, contextFiles: string[]): { updated: number; failed: number } {
+// 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;
+
+function enrichWithCopilotCli(
+  workspaceRoot: string,
+  contextFiles: string[],
+): { updated: number; failed: number } {
   let updated = 0;
   let failed = 0;
 
-  for (const absPath of contextFiles) {
-    const relPath = absPath.replace(`${workspaceRoot}/`, "");
+  // Limit the number of files processed in one init run.
+  const filesToProcess = contextFiles.slice(0, MAX_ENRICHMENT_FILES);
+  const total = filesToProcess.length;
+
+  for (let i = 0; i < filesToProcess.length; i++) {
+    const absPath = filesToProcess[i];
+    // 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}…`);
+
+    // 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 = [
-      `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.",
+      `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(
@@ -291,8 +330,6 @@ function enrichWithCopilotCli(workspaceRoot: string, contextFiles: string[]): {
       [
         "-C", workspaceRoot,
         "-p", prompt,
-        "--allow-all-tools",
-        "--allow-all-paths",
         "--no-color",
         "-s",
       ],
@@ -301,12 +338,29 @@ function enrichWithCopilotCli(workspaceRoot: string, contextFiles: string[]): {
         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) {
-      updated += 1;
+    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");
+        failed += 1;
+      }
     } else {
+      process.stdout.write(" ✗\n");
       failed += 1;
     }
   }
@@ -439,7 +493,9 @@ program
         // Wrap both the python path and requirements path in quotes so
         // Windows paths that contain spaces (e.g. "IGEL Automation July 2026")
         // are treated as a single argument by the shell.
-        execSync(`"${pyBin}" -m pip install -q -r "${reqPath}"`, {
+        // --prefer-binary: use pre-built wheels instead of compiling from source
+        // (avoids Rust/Cargo requirement for packages like tokenizers, crawl4ai)
+        execSync(`"${pyBin}" -m pip install -q --prefer-binary -r "${reqPath}"`, {
           cwd: workspaceRoot, stdio: "inherit",
         });
         console.log(chalk.green("   ✓ Dependencies installed"));
@@ -467,25 +523,36 @@ program
     }
 
 
-    // Step 2d — Copilot CLI enrichment pass (asks login if needed), then DB sync.
+    // Step 3d — Copilot CLI enrichment pass.
+    // Only run when --with-copilot / --with-all is explicitly requested.
+    // Skipped silently on plain `igel-qe init` to avoid unexpected long waits.
+    const runEnrichment = options.withCopilot || options.withAll;
     console.log(chalk.yellow("3d. Enriching context via GitHub Copilot CLI…"));
-    try {
-      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 run = enrichWithCopilotCli(workspaceRoot, allContextFiles);
-        console.log(chalk.green(`   ✓ Copilot updated ${run.updated} context.md file(s)`));
-        if (run.failed > 0) {
-          console.log(chalk.yellow(`   ⚠ Copilot failed to update ${run.failed} context.md file(s)`));
+    if (!runEnrichment) {
+      console.log(chalk.gray("   - Skipped (pass --with-copilot to enable Copilot context enrichment)"));
+    } else {
+      try {
+        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)`));
+          }
         }
+      } catch (e: unknown) {
+        console.log(chalk.yellow(`   ⚠ Copilot context enrichment skipped: ${e instanceof Error ? e.message : String(e)}`));
       }
-    } catch (e: unknown) {
-      console.log(chalk.yellow(`   ⚠ Copilot context enrichment skipped: ${e instanceof Error ? e.message : String(e)}`));
     }
 
     // Step 3 — write MCP config (default: Copilot when no explicit platform flags)

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,6 +113,28 @@ 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",):
         try:

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)