@thelogicatelier/sylva 1.0.11 → 1.0.13

package/dist/awareness/braveSearch.js

@@ -83,21 +83,24 @@ async function braveSearch(query, options) {
         });
         if (!response.ok) {
             const statusText = response.statusText || "Unknown error";
+            const errorMsg = `HTTP ${response.status} (${statusText})`;
             if (response.status === 401 || response.status === 403) {
                 console.warn(`❌ Brave Search API authentication failed (HTTP ${response.status}: ${statusText}).\n` +
                     `   Your BRAVE_API_KEY may be invalid or expired.\n` +
                     `   Get a valid key at: https://brave.com/search/api/\n` +
                     `   Framework detection still works — only web doc references are affected.`);
+                throw new Error(`Authentication failed ${errorMsg}. Valid API key required.`);
             }
             else if (response.status === 429) {
                 console.warn(`⚠️  Brave Search API rate limit exceeded (HTTP 429).\n` +
                     `   Query: "${query}"\n` +
                     `   Wait a moment and retry, or check your Brave API plan limits.`);
+                throw new Error(`Rate limit exceeded ${errorMsg}.`);
             }
             else {
                 console.warn(`⚠️  Brave Search API returned HTTP ${response.status} (${statusText}) for query: "${query}"`);
+                throw new Error(`Brave Search API error: ${errorMsg}`);
             }
-            return [];
         }
         const data = (await response.json());
         const webResults = data.web?.results || [];
@@ -120,10 +123,10 @@ async function braveSearch(query, options) {
             console.warn(`⚠️  Brave Search network error for query "${query}": ${errMsg}\n` +
                 `   Check your internet connection. Framework detection is unaffected.`);
         }
-        else {
+        else if (!errMsg.includes("HTTP")) {
             console.warn(`⚠️  Brave Search failed for query "${query}": ${errMsg}`);
         }
-        return [];
+        throw error;
     }
 }
 /**

package/dist/awareness/detector.d.ts

@@ -3,6 +3,7 @@
  * Deterministic — no LLM involvement.
  */
 import { Signal, StackInfo, ArchitectureModel, VersionInfo } from "./types";
+/** Confidence scoring rules */
 /**
  * Detect stacks from signals.
  * Groups signals by frameworkId and scores confidence.

package/dist/awareness/detector.js

@@ -8,37 +8,8 @@ exports.detectStacks = detectStacks;
 exports.detectArchitecture = detectArchitecture;
 exports.formatVersionForDisplay = formatVersionForDisplay;
 const versionResolver_1 = require("./versionResolver");
+const constants_1 = require("../constants");
 /** Confidence scoring rules */
-const CONFIDENCE_SCORES = {
-    orchestrator: 95,
-    angular: 85,
-    react: 80,
-    nextjs: 85,
-    vue: 80,
-    nuxt: 85,
-    svelte: 80,
-    sveltekit: 85,
-    express: 75,
-    nestjs: 85,
-    fastify: 75,
-    django: 85,
-    flask: 75,
-    fastapi: 80,
-    "spring-boot": 90,
-    spring: 80,
-    "java-maven": 70,
-    "java-gradle": 70,
-    dotnet: 80,
-    "aspnet-core": 85,
-    go: 80,
-    rust: 80,
-    "actix-web": 85,
-    axum: 85,
-    nodejs: 60,
-    python: 60,
-    typescript: 65,
-    docker: 50,
-};
 /**
  * Detect stacks from signals.
  * Groups signals by frameworkId and scores confidence.
@@ -46,8 +17,17 @@ const CONFIDENCE_SCORES = {
 function detectStacks(signals) {
     const grouped = new Map();
     for (const signal of signals) {
-        // Skip tooling/entrypoint signals for stack detection
-        if (signal.kind === "tooling" || signal.kind === "entrypoint")
+        // Skip non-framework signals from stack detection
+        if (signal.kind === "tooling" ||
+            signal.kind === "entrypoint" ||
+            signal.kind === "agent" ||
+            signal.kind === "subagent" ||
+            signal.kind === "heartbeat" ||
+            signal.kind === "cron" ||
+            signal.kind === "hook" ||
+            signal.kind === "skill" ||
+            signal.kind === "plugin" ||
+            signal.kind === "integration")
             continue;
         if (!grouped.has(signal.frameworkId)) {
             grouped.set(signal.frameworkId, []);
@@ -57,7 +37,7 @@ function detectStacks(signals) {
     const stacks = [];
     for (const [frameworkId, frameworkSignals] of grouped) {
         const frameworkName = frameworkSignals[0].frameworkName;
-        const confidence = CONFIDENCE_SCORES[frameworkId] || 50;
+        const confidence = constants_1.CONFIDENCE_SCORES[frameworkId] || 50;
         const version = (0, versionResolver_1.resolveVersion)(frameworkSignals);
         // Determine rootPath — use the shallowest signal's scope
         const rootPaths = frameworkSignals.map((s) => s.scope.pathRoot).filter(Boolean);

package/dist/awareness/index.js

@@ -46,11 +46,12 @@ const manifestParsers_1 = require("./manifestParsers");
 const versionResolver_1 = require("./versionResolver");
 const detector_1 = require("./detector");
 const webGrounding_1 = require("./webGrounding");
+const sourceScanner_1 = require("./sourceScanner");
 /**
  * The ARCHITECTURE CONSTRAINTS block injected into LLM context.
  * This is authoritative and must not be overridden by the model.
  */
-function buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator) {
+function buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator, signals) {
     const lines = [
         "=== ARCHITECTURE CONSTRAINTS (AUTHORITATIVE) ===",
         "1) The detected frameworks/stacks listed below are authoritative because they were derived from repository manifest/config files.",
@@ -78,9 +79,80 @@ function buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator) {
             lines.push(`    Evidence: ${ev.evidence.reason} [${ev.evidence.file}]`);
         }
     }
+    // OpenClaw-specific constraint sections (only when detected)
+    if (hasOrchestrator) {
+        appendOpenClawConstraints(lines, signals);
+    }
+    // External Integrations (source code scanner)
+    const integrations = signals.filter((s) => s.kind === "integration");
+    if (integrations.length > 0) {
+        lines.push("", "EXTERNAL INTEGRATIONS (Discovered in Source Code):");
+        for (const sig of integrations) {
+            lines.push(`  - ${sig.frameworkName}`);
+            lines.push(`    Evidence: ${sig.evidence.reason} [${sig.evidence.file}]`);
+        }
+    }
     lines.push("=== END ARCHITECTURE CONSTRAINTS ===");
     return lines.join("\n");
 }
+/**
+ * Append OpenClaw-specific sections to the constraints block.
+ * Groups signals by kind (agent, hook, skill, subagent, plugin, heartbeat).
+ */
+function appendOpenClawConstraints(lines, signals) {
+    // Agent config
+    const agentSignals = signals.filter((s) => s.kind === "agent");
+    if (agentSignals.length > 0) {
+        lines.push("", "OPENCLAW AGENT CONFIG:");
+        for (const sig of agentSignals) {
+            lines.push(`  - ${sig.frameworkName}: ${sig.evidence.excerpt}`);
+        }
+    }
+    // Hooks
+    const hookSignals = signals.filter((s) => s.kind === "hook");
+    if (hookSignals.length > 0) {
+        lines.push("", "OPENCLAW HOOKS:");
+        for (const sig of hookSignals) {
+            const name = sig.frameworkName.replace("OpenClaw Hook: ", "");
+            lines.push(`  - /${name}: ${sig.evidence.reason}`);
+        }
+    }
+    // Skills
+    const skillSignals = signals.filter((s) => s.kind === "skill");
+    if (skillSignals.length > 0) {
+        lines.push("", "OPENCLAW SKILLS:");
+        for (const sig of skillSignals) {
+            lines.push(`  - ${sig.frameworkName.replace("OpenClaw Skill: ", "")}: ${sig.evidence.reason}`);
+        }
+    }
+    // Subagents
+    const subagentSignals = signals.filter((s) => s.kind === "subagent");
+    if (subagentSignals.length > 0) {
+        lines.push("", "OPENCLAW SUBAGENTS:");
+        for (const sig of subagentSignals) {
+            lines.push(`  - ${sig.frameworkName.replace("OpenClaw Subagent: ", "")}: ${sig.evidence.reason}`);
+            if (sig.evidence.excerpt) {
+                lines.push(`    ${sig.evidence.excerpt}`);
+            }
+        }
+    }
+    // Plugins
+    const pluginSignals = signals.filter((s) => s.kind === "plugin");
+    if (pluginSignals.length > 0) {
+        lines.push("", "OPENCLAW PLUGINS:");
+        for (const sig of pluginSignals) {
+            lines.push(`  - ${sig.frameworkName.replace("OpenClaw Plugin: ", "")}: ${sig.evidence.excerpt}`);
+        }
+    }
+    // Heartbeat
+    const heartbeatSignals = signals.filter((s) => s.kind === "heartbeat");
+    if (heartbeatSignals.length > 0) {
+        lines.push("", "OPENCLAW HEARTBEAT:");
+        for (const sig of heartbeatSignals) {
+            lines.push(`  - ${sig.evidence.excerpt}`);
+        }
+    }
+}
 /**
  * Build the full awareness context string for LLM prompts.
  */
@@ -170,6 +242,65 @@ function saveAwarenessJson(repoName, result, baseDir = "projects") {
             `   Check disk space and directory write permissions if you need this output.`);
     }
 }
+/**
+ * Save grounding.json for web grounding transparency.
+ * Always saved — contains references + structured errors.
+ */
+function saveGroundingJson(repoName, webReferences, errors, baseDir = "projects") {
+    const folderName = repoName.toLowerCase().replace(/\s+/g, "-");
+    const targetDir = path.join(baseDir, folderName);
+    fs.mkdirSync(targetDir, { recursive: true });
+    const filePath = path.join(targetDir, "grounding.json");
+    try {
+        // Build structured error entries
+        const structuredErrors = errors.map((err) => {
+            // Parse known error patterns
+            if (err.includes("BRAVE_API_KEY not set")) {
+                return {
+                    reason: "BRAVE_API_KEY not set",
+                    impact: "Web grounding disabled — no documentation references gathered",
+                    resolution: "Set BRAVE_API_KEY in your .env file. Get a free key at https://brave.com/search/api/",
+                };
+            }
+            if (err.includes("rate limit") || err.includes("HTTP 429")) {
+                const queryMatch = err.match(/Query: "([^"]+)"/);
+                return {
+                    query: queryMatch ? queryMatch[1] : undefined,
+                    reason: "Brave Search API rate limit exceeded (HTTP 429)",
+                    impact: "Results missing for this query",
+                    resolution: "Wait a moment and retry, or check your Brave API plan limits",
+                };
+            }
+            if (err.includes("Web search failed")) {
+                const queryMatch = err.match(/for "([^"]+)"/);
+                const reasonMatch = err.match(/: (.+)$/);
+                return {
+                    query: queryMatch ? queryMatch[1] : undefined,
+                    reason: reasonMatch ? reasonMatch[1] : err,
+                    impact: "Results missing for this query",
+                };
+            }
+            return {
+                reason: err,
+                impact: "Unknown web grounding error",
+            };
+        });
+        const grounding = {
+            generatedAt: new Date().toISOString(),
+            totalReferences: webReferences.reduce((sum, ref) => sum + ref.results.length, 0),
+            frameworksCovered: webReferences.length,
+            references: webReferences,
+            errors: structuredErrors,
+        };
+        fs.writeFileSync(filePath, JSON.stringify(grounding, null, 2), "utf-8");
+        console.log(`✅ Saved grounding.json to: ${filePath}`);
+    }
+    catch (error) {
+        console.warn(`⚠️  Could not save grounding.json to ${filePath}: ${error.message}\n` +
+            `   This is a debug file and does not affect AGENTS.md generation.\n` +
+            `   Check disk space and directory write permissions if you need this output.`);
+    }
+}
 /**
  * Run the full awareness pipeline.
  * This is the main entry point called from the CLI.
@@ -190,8 +321,16 @@ async function runAwareness(repoPath, repoName) {
     }
     // Step 2: Parse all manifests into signals
     console.log("  → Parsing manifests...");
-    const signals = (0, manifestParsers_1.parseAllManifests)(manifests);
-    console.log(`  → Generated ${signals.length} signal(s)`);
+    const manifestSignals = (0, manifestParsers_1.parseAllManifests)(manifests);
+    console.log(`  → Generated ${manifestSignals.length} signal(s) from manifests`);
+    // Step 2.5: Scan source code for external integrations
+    console.log("  → Scanning source code for external integrations...");
+    const integrationSignals = (0, sourceScanner_1.scanSourceFiles)(repoPath);
+    if (integrationSignals.length > 0) {
+        console.log(`  → Discovered ${integrationSignals.length} integration(s) in source code`);
+    }
+    // Merge all signals
+    const signals = [...manifestSignals, ...integrationSignals];
     // Step 3: Resolve versions
     console.log("  → Resolving versions...");
     const resolvedVersions = (0, versionResolver_1.resolveAllVersions)(signals);
@@ -210,9 +349,28 @@ async function runAwareness(repoPath, repoName) {
     }
     if (hasOrchestrator) {
         console.log("    🎯 OpenClaw orchestrator detected");
+        // Log OpenClaw-specific discoveries
+        const hookCount = signals.filter((s) => s.kind === "hook").length;
+        const skillCount = signals.filter((s) => s.kind === "skill").length;
+        const subagentCount = signals.filter((s) => s.kind === "subagent").length;
+        const pluginCount = signals.filter((s) => s.kind === "plugin").length;
+        if (hookCount > 0)
+            console.log(`    🪝 ${hookCount} hook(s) detected`);
+        if (skillCount > 0)
+            console.log(`    🎯 ${skillCount} skill(s) detected`);
+        if (subagentCount > 0)
+            console.log(`    🤖 ${subagentCount} subagent(s) detected`);
+        if (pluginCount > 0)
+            console.log(`    🔌 ${pluginCount} plugin(s) detected`);
+        const heartbeat = signals.find((s) => s.kind === "heartbeat");
+        if (heartbeat) {
+            const active = heartbeat.evidence.excerpt?.includes("ACTIVE") &&
+                !heartbeat.evidence.excerpt?.includes("INACTIVE");
+            console.log(`    💓 Heartbeat: ${active ? "ACTIVE" : "INACTIVE"}`);
+        }
     }
-    // Step 5: Build constraints block
-    const constraintsBlock = buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator);
+    // Step 5: Build constraints block (now includes OpenClaw-specific sections)
+    const constraintsBlock = buildConstraintsBlock(stacks, resolvedVersions, hasOrchestrator, signals);
     // Step 6: Web grounding
     console.log("  → Gathering web references...");
     const cacheDir = path.join("projects", repoName.toLowerCase().replace(/\s+/g, "-"), "cache", "brave");
@@ -254,6 +412,8 @@ async function runAwareness(repoPath, repoName) {
     };
     // Step 8: Save awareness.json
     saveAwarenessJson(repoName, result);
+    // Step 9: Save grounding.json (always, even on errors)
+    saveGroundingJson(repoName, webReferences, errors);
     console.log("✅ Framework Awareness scan complete\n");
     return result;
 }

package/dist/awareness/manifestParsers/goParsers.js

@@ -40,16 +40,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseGoMod = parseGoMod;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-/** Known Go frameworks/libraries */
-const GO_FRAMEWORKS = [
-    { module: "github.com/gin-gonic/gin", frameworkId: "gin", frameworkName: "Gin" },
-    { module: "github.com/labstack/echo", frameworkId: "echo", frameworkName: "Echo" },
-    { module: "github.com/gofiber/fiber", frameworkId: "fiber", frameworkName: "Fiber" },
-    { module: "github.com/gorilla/mux", frameworkId: "gorilla-mux", frameworkName: "Gorilla Mux" },
-    { module: "gorm.io/gorm", frameworkId: "gorm", frameworkName: "GORM" },
-    { module: "github.com/stretchr/testify", frameworkId: "testify", frameworkName: "Testify" },
-    { module: "google.golang.org/grpc", frameworkId: "grpc-go", frameworkName: "gRPC-Go" },
-];
+const constants_1 = require("../../constants");
 /**
  * Parse go.mod
  */
@@ -117,7 +108,7 @@ function parseGoMod(manifest) {
             continue;
         const modulePath = match[1];
         const version = match[2];
-        const framework = GO_FRAMEWORKS.find((f) => modulePath.startsWith(f.module));
+        const framework = constants_1.GO_FRAMEWORKS.find((f) => modulePath.startsWith(f.module));
         if (framework) {
             signals.push({
                 kind: "framework",

package/dist/awareness/manifestParsers/javaParsers.js

@@ -41,25 +41,7 @@ exports.parsePomXml = parsePomXml;
 exports.parseBuildGradle = parseBuildGradle;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-/** Known Java frameworks */
-const JAVA_FRAMEWORKS = [
-    {
-        groupArtifact: "org.springframework.boot",
-        frameworkId: "spring-boot",
-        frameworkName: "Spring Boot",
-    },
-    {
-        groupArtifact: "org.springframework",
-        frameworkId: "spring",
-        frameworkName: "Spring Framework",
-    },
-    { groupArtifact: "io.quarkus", frameworkId: "quarkus", frameworkName: "Quarkus" },
-    { groupArtifact: "io.micronaut", frameworkId: "micronaut", frameworkName: "Micronaut" },
-    { groupArtifact: "org.hibernate", frameworkId: "hibernate", frameworkName: "Hibernate" },
-    { groupArtifact: "junit", frameworkId: "junit", frameworkName: "JUnit" },
-    { groupArtifact: "org.junit", frameworkId: "junit5", frameworkName: "JUnit 5" },
-    { groupArtifact: "org.apache.kafka", frameworkId: "kafka", frameworkName: "Apache Kafka" },
-];
+const constants_1 = require("../../constants");
 /**
  * Parse pom.xml (Maven)
  */
@@ -108,7 +90,7 @@ function parsePomXml(manifest) {
     if (parentMatch) {
         const parentGroup = parentMatch[1];
         const parentVersion = parentMatch[2];
-        const framework = JAVA_FRAMEWORKS.find((f) => parentGroup.includes(f.groupArtifact));
+        const framework = constants_1.JAVA_FRAMEWORKS.find((f) => parentGroup.includes(f.groupArtifact));
         if (framework) {
             const resolvedVersion = parentVersion.startsWith("${")
                 ? properties[parentVersion.slice(2, -1)]
@@ -141,7 +123,7 @@ function parsePomXml(manifest) {
         const groupId = depMatch[1];
         const artifactId = depMatch[2];
         const version = depMatch[3];
-        const framework = JAVA_FRAMEWORKS.find((f) => groupId.includes(f.groupArtifact));
+        const framework = constants_1.JAVA_FRAMEWORKS.find((f) => groupId.includes(f.groupArtifact));
         if (framework) {
             let versionInfo;
             if (version) {
@@ -223,7 +205,7 @@ function parseBuildGradle(manifest) {
     while ((m = depRegex.exec(content)) !== null) {
         const groupId = m[1];
         const version = m[3];
-        const framework = JAVA_FRAMEWORKS.find((f) => groupId.includes(f.groupArtifact));
+        const framework = constants_1.JAVA_FRAMEWORKS.find((f) => groupId.includes(f.groupArtifact));
         if (framework) {
             signals.push({
                 kind: "framework",

package/dist/awareness/manifestParsers/openclawParser.d.ts

@@ -1,6 +1,20 @@
 /**
- * OpenClaw manifest parser.
- * Parses openclaw.json to extract orchestrator configuration.
+ * OpenClaw manifest parser — deep extraction.
+ * Parses openclaw.json / .openclaw.json to extract:
+ *   - Orchestrator signal with version from meta
+ *   - Agent config (models, workspace, concurrency)
+ *   - Hooks (internal event scripts with paths + descriptions)
+ *   - Plugins (enabled extensions)
+ *   - Gateway config (port, auth, denied commands)
+ *   - Channels (policies, stream modes)
+ *   - Tools (web search, fetch)
+ *   - Commands / messages config
+ *
+ * Also scans the OpenClaw workspace directory for:
+ *   - Skills (reusable .md workflows)
+ *   - Subagents (background agent directories)
+ *   - Workspace .md files (AGENTS.md, IDENTITY.md, HEARTBEAT.md, etc.)
+ *   - Hook scripts
  */
 import { Signal, ManifestFile } from "../types";
 export declare function parseOpenclawJson(manifest: ManifestFile): Signal[];