@lousy-agents/cli 5.11.4 → 5.12.0

package/api/copilot-with-fastify/package-lock.json

@@ -18,11 +18,11 @@
             },
             "devDependencies": {
                 "@biomejs/biome": "2.4.13",
-                "@lousy-agents/mcp": "5.11.3",
+                "@lousy-agents/mcp": "5.11.4",
                 "@modelcontextprotocol/server-sequential-thinking": "2025.12.18",
                 "@testcontainers/postgresql": "11.14.0",
                 "@types/node": "24.12.2",
-                "@upstash/context7-mcp": "2.2.0",
+                "@upstash/context7-mcp": "2.2.1",
                 "chance": "1.1.13",
                 "testcontainers": "11.14.0",
                 "tsx": "4.21.0",
@@ -956,9 +956,9 @@
             }
         },
         "node_modules/@lousy-agents/mcp": {
-            "version": "5.11.3",
-            "resolved": "https://registry.npmjs.org/@lousy-agents/mcp/-/mcp-5.11.3.tgz",
-            "integrity": "sha512-J/XUOmJwpArU99A4ObeE63XEhyrga8L3kIFex1Jl2mbUkcIhz7bakvZ1SCgj34FI02ygxk0Z/K0QKBTDTWgqsQ==",
+            "version": "5.11.4",
+            "resolved": "https://registry.npmjs.org/@lousy-agents/mcp/-/mcp-5.11.4.tgz",
+            "integrity": "sha512-3hhhpJcopMWdXBT8cR4gHF9ieCNzDtwQDGWidKeSzbaq8+dW2t0zU0Znow+JW1lxjx3QuI68S09J4id6FpZqow==",
             "dev": true,
             "license": "BSD-2-Clause-Patent",
             "dependencies": {
@@ -1649,9 +1649,9 @@
             "license": "MIT"
         },
         "node_modules/@upstash/context7-mcp": {
-            "version": "2.2.0",
-            "resolved": "https://registry.npmjs.org/@upstash/context7-mcp/-/context7-mcp-2.2.0.tgz",
-            "integrity": "sha512-AYcvmMWaf2HsZMdp8eURiHwGB+0MF4IDkG9IB22Th9OfoCWL5rldeSL7pEFxxaWBcRl0yOga1exo+1Ga4d2vMA==",
+            "version": "2.2.1",
+            "resolved": "https://registry.npmjs.org/@upstash/context7-mcp/-/context7-mcp-2.2.1.tgz",
+            "integrity": "sha512-0Uu7GekKYaP/sgSCeoClYFqCm00rqehMFfHhj14krs0cVkVVz9vrChhZdV5kmkYDNNnQ7Vd6F5b57evina2+5w==",
             "dev": true,
             "license": "MIT",
             "dependencies": {

package/api/copilot-with-fastify/package.json

@@ -26,11 +26,11 @@
     },
     "devDependencies": {
         "@biomejs/biome": "2.4.13",
-        "@lousy-agents/mcp": "5.11.3",
+        "@lousy-agents/mcp": "5.11.4",
         "@modelcontextprotocol/server-sequential-thinking": "2025.12.18",
         "@testcontainers/postgresql": "11.14.0",
         "@types/node": "24.12.2",
-        "@upstash/context7-mcp": "2.2.0",
+        "@upstash/context7-mcp": "2.2.1",
         "chance": "1.1.13",
         "testcontainers": "11.14.0",
         "tsx": "4.21.0",

package/cli/copilot-with-citty/package.json

@@ -20,10 +20,10 @@
     },
     "devDependencies": {
         "@biomejs/biome": "2.4.13",
-        "@lousy-agents/mcp": "5.11.3",
+        "@lousy-agents/mcp": "5.11.4",
         "@modelcontextprotocol/server-sequential-thinking": "2025.12.18",
         "@types/node": "24.12.2",
-        "@upstash/context7-mcp": "2.2.0",
+        "@upstash/context7-mcp": "2.2.1",
         "chance": "1.1.13",
         "tsx": "4.21.0",
         "typescript": "6.0.3",

package/dist/index.js

@@ -47095,7 +47095,8 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
         "instruction/parse-error": "warn",
         "instruction/command-not-in-code-block": "warn",
         "instruction/command-outside-section": "warn",
-        "instruction/missing-error-handling": "warn"
+        "instruction/missing-error-handling": "warn",
+        "instruction/missing-structural-heading": "warn"
     },
     skills: {
         "skill/invalid-frontmatter": "error",
@@ -47188,6 +47189,24 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
     "Validation Suite",
     "Commands"
 ];
+/**
+ * Descriptions for each default structural heading pattern explaining why it is recommended.
+ * Keyed by Record<StructuralHeadingPattern, string> to ensure compile-time coverage — every
+ * entry in DEFAULT_STRUCTURAL_HEADING_PATTERNS must have a description here.
+ */ const HEADING_PATTERN_DESCRIPTION_RECORD = {
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Validation: "Agents need this section to understand how to validate that their changes meet quality standards.",
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Verification: "Agents need this section to understand how to verify their implementation is correct.",
+    "Feedback Loop": "Agents need this section to understand the iterative improvement process to follow.",
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Mandatory: "Agents need this section to understand which steps are required and cannot be skipped.",
+    "Before Commit": "Agents need this section to know what checks to run before committing changes.",
+    "Validation Suite": "Agents need this section to know which validation commands to run against the codebase.",
+    // biome-ignore lint/style/useNamingConvention: heading pattern keys use PascalCase by design
+    Commands: "Agents need this section to know which commands and tools are available in the project."
+};
+const HEADING_PATTERN_DESCRIPTIONS = new Map(Object.entries(HEADING_PATTERN_DESCRIPTION_RECORD));
 /** Conditional keywords indicating error handling near code blocks */ const CONDITIONAL_KEYWORDS = [
     "if",
     "fail",
@@ -47207,6 +47226,24 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
  * Use case for analyzing instruction quality across a repository.
  * Orchestrates discovery, AST parsing, and scoring of feedback loop documentation.
  */ 
+
+/** Maximum number of raw heading pattern entries accepted before deduplication. */ const MAX_RAW_HEADING_PATTERNS = 1000;
+/** Maximum number of heading patterns accepted in a single execute() call. */ const MAX_HEADING_PATTERNS = 50;
+/** Maximum character length for a single heading pattern. */ const MAX_PATTERN_LENGTH = 200;
+/**
+ * Lowercase-keyed lookup built once from HEADING_PATTERN_DESCRIPTIONS.
+ * Enables description lookup regardless of the casing callers supply for patterns.
+ */ const HEADING_DESCRIPTIONS_BY_LOWER = new Map(Array.from(HEADING_PATTERN_DESCRIPTIONS, ([k, v])=>[
+        k.toLowerCase(),
+        v
+    ]));
+/**
+ * Input for the analyze instruction quality use case.
+ */ const AnalyzeInstructionQualityInputSchema = schemas_object({
+    targetDir: schemas_string().min(1, "Target directory is required"),
+    headingPatterns: schemas_array(schemas_string().max(MAX_PATTERN_LENGTH * 2)).max(MAX_RAW_HEADING_PATTERNS).optional(),
+    proximityWindow: schemas_number().int().positive().optional()
+});
 /**
  * Use case for analyzing instruction quality.
  */ class AnalyzeInstructionQualityUseCase {
@@ -47218,16 +47255,107 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
         this.astGateway = astGateway;
         this.commandsGateway = commandsGateway;
     }
+    /**
+     * Returns true if the given heading-pattern string contains any characters
+     * that could cause terminal injection or garbled output when the pattern
+     * is embedded in a diagnostic message.
+     *
+     * Rejects: ASCII C0 (0x00–0x1F), DEL (0x7F), C1 (0x80–0x9F), **lone**
+     * Unicode surrogates (U+D800–U+DFFF — but valid surrogate pairs like emoji
+     * are accepted), line/paragraph separators (U+2028–U+2029), and bidi
+     * override characters (U+202A–U+202E, U+2066–U+2069).
+     */ static patternHasControlCharacters(value) {
+        for(let i = 0; i < value.length; i++){
+            const code = value.charCodeAt(i);
+            if (code <= 0x1f) return true;
+            if (code === 0x7f) return true;
+            if (code >= 0x80 && code <= 0x9f) return true;
+            // Detect lone surrogates only; valid surrogate pairs (e.g., emoji)
+            // should be accepted. A high surrogate (0xD800–0xDBFF) is lone if
+            // it is not immediately followed by a low surrogate (0xDC00–0xDFFF).
+            if (code >= 0xd800 && code <= 0xdbff) {
+                const next = value.charCodeAt(i + 1);
+                if (next >= 0xdc00 && next <= 0xdfff) {
+                    i++; // valid pair — skip the low surrogate
+                } else {
+                    return true; // lone high surrogate
+                }
+            } else if (code >= 0xdc00 && code <= 0xdfff) {
+                return true; // lone low surrogate
+            }
+            if (code === 0x2028 || code === 0x2029) return true;
+            if (code >= 0x202a && code <= 0x202e) return true;
+            if (code >= 0x2066 && code <= 0x2069) return true;
+        }
+        return false;
+    }
+    /**
+     * Serializes a heading pattern for safe inclusion in error messages.
+     * Produces a quoted, unambiguous representation by:
+     *   - Escaping `"` as `\"` and `\` as `\\` within printable ASCII (0x20–0x7E)
+     *   - Escaping every code unit outside that range to `\uXXXX`
+     *
+     * The \uXXXX escaping prevents terminal injection via bidi override
+     * characters and other non-printable code points that JSON.stringify does
+     * not escape.
+     */ static serializePatternForError(value) {
+        let result = '"';
+        for(let i = 0; i < value.length; i++){
+            const code = value.charCodeAt(i);
+            if (code >= 0x20 && code <= 0x7e) {
+                if (code === 0x22) {
+                    result += '\\"';
+                } else if (code === 0x5c) {
+                    result += "\\\\";
+                } else {
+                    result += value[i];
+                }
+            } else {
+                result += `\\u${code.toString(16).padStart(4, "0")}`;
+            }
+        }
+        return `${result}"`;
+    }
     async execute(input) {
-        if (!input.targetDir) {
-            throw new Error("Target directory is required");
+        let parsed;
+        try {
+            parsed = AnalyzeInstructionQualityInputSchema.parse(input);
+        } catch (error) {
+            if (error instanceof ZodError) {
+                throw new Error(error.issues[0]?.message ?? "Validation failed: unable to parse error details");
+            }
+            throw error;
         }
-        const headingPatterns = input.headingPatterns ?? [
+        const seenLower = new Set();
+        const headingPatterns = [];
+        for (const raw of parsed.headingPatterns ?? [
             ...DEFAULT_STRUCTURAL_HEADING_PATTERNS
-        ];
-        const proximityWindow = input.proximityWindow ?? 3;
-        const discoveredFiles = await this.discoveryGateway.discoverInstructionFiles(input.targetDir);
-        const mandatoryCommands = await this.commandsGateway.getMandatoryCommands(input.targetDir);
+        ]){
+            // Validate BEFORE trim() — U+2028/U+2029 are JavaScript whitespace
+            // and would be silently stripped by trim(), bypassing the check.
+            // Filter before transform.
+            if (AnalyzeInstructionQualityUseCase.patternHasControlCharacters(raw)) {
+                throw new Error(`headingPatterns must not contain control characters, bidi override characters, or lone surrogate code points: ${AnalyzeInstructionQualityUseCase.serializePatternForError(raw)}`);
+            }
+            const trimmed = raw.trim();
+            if (trimmed.length === 0) {
+                throw new Error("headingPatterns must not contain empty or whitespace-only entries");
+            }
+            if (trimmed.length > MAX_PATTERN_LENGTH) {
+                throw new Error(`headingPatterns entries must not exceed ${MAX_PATTERN_LENGTH} characters`);
+            }
+            const lower = trimmed.toLowerCase();
+            if (!seenLower.has(lower)) {
+                seenLower.add(lower);
+                if (seenLower.size > MAX_HEADING_PATTERNS) {
+                    throw new Error(`headingPatterns must contain at most ${MAX_HEADING_PATTERNS} unique entries (case-insensitive)`);
+                }
+                headingPatterns.push(trimmed);
+            }
+        }
+        const proximityWindow = parsed.proximityWindow ?? 3;
+        const discoveredFiles = await this.discoveryGateway.discoverInstructionFiles(parsed.targetDir);
+        const mandatoryCommands = await this.commandsGateway.getMandatoryCommands(parsed.targetDir);
         if (discoveredFiles.length === 0) {
             return {
                 result: {
@@ -47260,7 +47388,7 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
             }
         }
         // Sort parsing errors for deterministic output
-        parsingErrors.sort((a, b)=>a.filePath.localeCompare(b.filePath));
+        parsingErrors.sort((a, b)=>a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0);
         // Score each mandatory command across all files
         const commandScores = [];
         const diagnostics = [];
@@ -47275,6 +47403,16 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
                 target: "instruction"
             });
         }
+        // Check each successfully parsed file for missing structural headings
+        const sortedFilePaths = Array.from(fileStructures.keys()).sort((a, b)=>a < b ? -1 : a > b ? 1 : 0);
+        for (const filePath of sortedFilePaths){
+            const structure = fileStructures.get(filePath);
+            if (!structure) {
+                continue;
+            }
+            const missingDiagnostics = this.checkMissingHeadings(filePath, structure, headingPatterns);
+            diagnostics.push(...missingDiagnostics);
+        }
         for (const command of mandatoryCommands){
             const bestAnalysis = this.findBestScore(command, discoveredFiles, fileStructures, headingPatterns, proximityWindow, diagnostics);
             if (bestAnalysis) {
@@ -47516,6 +47654,43 @@ const remark = unified().use(remarkParse).use(remarkStringify).freeze()
         }
         return false;
     }
+    /**
+     * Emits a warning diagnostic for each heading pattern that is absent from the file.
+     * Headings are matched case-insensitively using substring inclusion, matching the
+     * same logic used elsewhere in the use case.
+     */ checkMissingHeadings(filePath, structure, headingPatterns) {
+        // Precondition: `headingPatterns` must already be deduplicated
+        // (case-insensitively) and validated. This invariant is enforced by
+        // `execute()` before calling this method.
+        const diagnostics = [];
+        const fileHeadingTexts = structure.headings.map((h)=>h.text.toLowerCase());
+        for (const pattern of headingPatterns){
+            const patternLower = pattern.toLowerCase();
+            const hasHeading = fileHeadingTexts.some((text)=>{
+                if (!text.includes(patternLower)) {
+                    return false;
+                }
+                // Don't let a heading satisfy a shorter pattern when it also satisfies
+                // a longer, more-specific pattern that starts with the shorter one.
+                // E.g., a "Validation Suite" heading satisfies "Validation Suite" but
+                // should NOT also satisfy "Validation".
+                const supersededByMoreSpecific = headingPatterns.some((other)=>other !== pattern && other.toLowerCase().startsWith(patternLower) && text.includes(other.toLowerCase()));
+                return !supersededByMoreSpecific;
+            });
+            if (!hasHeading) {
+                const description = HEADING_DESCRIPTIONS_BY_LOWER.get(patternLower) ?? "This heading helps guide coding agents through structured workflows.";
+                diagnostics.push({
+                    filePath,
+                    line: 1,
+                    severity: "warning",
+                    message: `Missing '${pattern}' heading section. ${description}`,
+                    ruleId: "instruction/missing-structural-heading",
+                    target: "instruction"
+                });
+            }
+        }
+        return diagnostics;
+    }
     generateSuggestions(commandScores) {
         const suggestions = [];
         const lowStructural = commandScores.filter((s)=>s.structuralContext === 0 && s.bestSourceFile !== "");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lousy-agents/cli",
-    "version": "5.11.4",
+    "version": "5.12.0",
     "description": "CLI scaffolding tool that sets up projects with structure, instructions, and feedback loops for AI coding assistants",
     "type": "module",
     "repository": {

package/ui/copilot-with-react/package.json

@@ -23,20 +23,20 @@
     "devDependencies": {
         "@biomejs/biome": "2.4.13",
         "@eslint/eslintrc": "3.3.5",
-        "@lousy-agents/mcp": "5.11.3",
+        "@lousy-agents/mcp": "5.11.4",
         "@modelcontextprotocol/server-sequential-thinking": "2025.12.18",
         "@testing-library/jest-dom": "6.9.1",
         "@testing-library/react": "16.3.2",
         "@types/node": "24.12.2",
         "@types/react": "19.2.14",
         "@types/react-dom": "19.2.3",
-        "@upstash/context7-mcp": "2.2.0",
+        "@upstash/context7-mcp": "2.2.1",
         "@vitejs/plugin-react": "6.0.1",
         "@vitest/ui": "4.1.5",
         "eslint": "10.2.1",
         "eslint-config-next": "16.2.4",
         "happy-dom": "20.9.0",
-        "jsdom": "29.0.2",
+        "jsdom": "29.1.0",
         "typescript": "6.0.3",
         "vitest": "4.1.5",
         "whatwg-fetch": "3.6.20"