@thelogicatelier/sylva 1.0.13 → 1.0.15

package/README.md

@@ -80,11 +80,11 @@ npx @thelogicatelier/sylva --local-repository . -m openai/gpt-5.2 -i 25
 
 For detailed guidance, see the [Choosing the Right Model](https://achatt89.github.io/sylva/models/choosing.html) and [Iteration Depth Guide](https://achatt89.github.io/sylva/models/iterations.html) docs.
 
-### Framework Awareness (NEW)
+### Framework & Integration Awareness (NEW)
 
-Sylva now includes **deterministic framework detection** that scans the entire repository (including nested subprojects and monorepos) for manifest files before invoking the LLM. This prevents framework hallucination and produces more accurate `AGENTS.md` output.
+Sylva now includes **deterministic framework detection** and **source code integration scanning** that scans the entire repository (including nested subprojects and monorepos) before invoking the LLM. This prevents framework hallucination and produces more accurate `AGENTS.md` output.
 
-**What it detects:**
+**What it detects via Manifests:**
 - **OpenClaw** (`openclaw.json`) — treated as the primary orchestrator
 - **Node.js/JS/TS** — React, Angular, Vue, Next.js, Express, NestJS, etc. from `package.json`
 - **Python** — Django, Flask, FastAPI from `requirements.txt`, `pyproject.toml`, `Pipfile`
@@ -93,11 +93,16 @@ Sylva now includes **deterministic framework detection** that scans the entire r
 - **Go** — Gin, Echo, Fiber from `go.mod`
 - **Rust** — Actix, Axum, Tokio from `Cargo.toml`
 
+**What it detects via Source Scanning (Integrations & Deployments):**
+- **Deployment Platforms** — Fly.io, Railway, Render, AWS, GCP, Azure, DigitalOcean via `fly.toml`, `railway.json`, `app.yaml`, or even `Dockerfile` base image inspection.
+- **External APIs** — Stripe, Wix, AWS, Instagram Graph API via raw API URL regex matching or SDK imports directly in the source code.
+- **Strict Security** — It automatically ignores `.env` files entirely to prevent secret leakage and strictly respects the `.gitignore`.
+
 **Version certainty:** Versions are only reported when explicitly found in manifest/lockfiles. Never assumed.
 
-**Web grounding:** When `BRAVE_API_KEY` is set, Sylva fetches official docs for detected frameworks (version-specific when exact versions are known, latest fallback otherwise).
+**Web grounding:** When `BRAVE_API_KEY` is set, Sylva fetches official docs for detected frameworks (version-specific when exact versions are known, latest fallback otherwise) to feed into the architecture constraints. Note: It intelligently rate-limits itself to respect the Brave Free Tier (1 req/s).
 
-**Debug output:** `awareness.json` is saved alongside `AGENTS.md` for full transparency.
+**Debug output:** `awareness.json` and `grounding.json` are saved alongside `AGENTS.md` for full transparency.
 
 ### Environment Overrides
 - `AUTOSKILL_MODEL`: Set this to `gemini` or `anthropic` or `openai` to change the default execution provider globally without providing `-m` on every execution.

package/dist/awareness/braveSearch.js

@@ -49,6 +49,8 @@ const BRAVE_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search";
 function cacheKey(query) {
     return crypto.createHash("md5").update(query).digest("hex");
 }
+let lastRequestTime = 0;
+const RATE_LIMIT_MS = 1100; // 1.1 seconds to be safe
 /**
  * Search Brave API for a query. Returns parsed results.
  * Caches results to disk if cacheDir is provided.
@@ -74,6 +76,12 @@ async function braveSearch(query, options) {
     }
     try {
         const url = `${BRAVE_SEARCH_URL}?q=${encodeURIComponent(query)}&count=5`;
+        const now = Date.now();
+        const timeSinceLast = now - lastRequestTime;
+        if (timeSinceLast < RATE_LIMIT_MS) {
+            await new Promise((resolve) => setTimeout(resolve, RATE_LIMIT_MS - timeSinceLast));
+        }
+        lastRequestTime = Date.now();
         const response = await fetch(url, {
             headers: {
                 Accept: "application/json",
@@ -81,6 +89,7 @@ async function braveSearch(query, options) {
                 "X-Subscription-Token": apiKey,
             },
         });
+        lastRequestTime = Date.now();
         if (!response.ok) {
             const statusText = response.statusText || "Unknown error";
             const errorMsg = `HTTP ${response.status} (${statusText})`;

package/dist/awareness/sourceScanner.js

@@ -43,6 +43,15 @@ const ignore_1 = __importDefault(require("ignore"));
 const constants_1 = require("../constants");
 const MAX_SCAN_FILES = 200;
 const MAX_LINES_PER_FILE = 500;
+// Precompute known config files and docker files for fast lookup
+const CONFIG_FILE_NAMES = new Set();
+for (const int of constants_1.INTEGRATIONS) {
+    if (int.configPatterns) {
+        for (const pat of int.configPatterns)
+            CONFIG_FILE_NAMES.add(pat);
+    }
+}
+const DOCKER_FILE_NAMES = new Set(["docker-compose.yml", "docker-compose.yaml"]);
 /**
  * Loads .gitignore rules from the root if available
  */
@@ -92,7 +101,12 @@ function collectSourceFiles(dir, ig, rootPath, files = []) {
             }
             else if (entry.isFile()) {
                 const ext = path.extname(entry.name).toLowerCase();
-                if (constants_1.SOURCE_EXTENSIONS.includes(ext)) {
+                const baseName = entry.name;
+                const lowerBaseName = baseName.toLowerCase();
+                if (constants_1.SOURCE_EXTENSIONS.includes(ext) ||
+                    CONFIG_FILE_NAMES.has(baseName) ||
+                    DOCKER_FILE_NAMES.has(lowerBaseName) ||
+                    lowerBaseName.includes("dockerfile")) {
                     files.push(fullPath);
                 }
             }
@@ -123,6 +137,31 @@ function scanSourceFiles(rootPath) {
     const detectedIntegrationIds = new Set();
     for (const file of targetFiles) {
         try {
+            const fileName = path.basename(file);
+            const lowerFileName = fileName.toLowerCase();
+            const isDocker = lowerFileName.includes("dockerfile") || DOCKER_FILE_NAMES.has(lowerFileName);
+            // 1. Check exact config file matches (no file reading required)
+            for (const integration of constants_1.INTEGRATIONS) {
+                if (detectedIntegrationIds.has(integration.id))
+                    continue;
+                if (integration.configPatterns?.includes(fileName)) {
+                    detectedIntegrationIds.add(integration.id);
+                    signals.push({
+                        kind: "integration",
+                        frameworkId: integration.id,
+                        frameworkName: integration.name,
+                        version: { certainty: "unknown", value: undefined },
+                        evidence: {
+                            file: path.relative(rootPath, file),
+                            reason: `Source code scanner detected ${integration.name}: Found config file "${fileName}"`,
+                        },
+                        scope: { pathRoot: rootPath },
+                    });
+                }
+            }
+            // If we found everything, stop scanning
+            if (detectedIntegrationIds.size === constants_1.INTEGRATIONS.length)
+                break;
             // Read file and limit to N lines to keep it fast
             const contentRaw = fs.readFileSync(file, "utf-8");
             let content = contentRaw;
@@ -130,25 +169,35 @@ function scanSourceFiles(rootPath) {
             if (lines.length > MAX_LINES_PER_FILE) {
                 content = lines.slice(0, MAX_LINES_PER_FILE).join("\n");
             }
-            // Check all integrations against this chunk
+            // 2. Content Checks
             for (const integration of constants_1.INTEGRATIONS) {
                 if (detectedIntegrationIds.has(integration.id))
                     continue; // Found it already somewhere
                 let reason = "";
                 let matchedPattern = "";
-                matchedPattern = matchPatterns(content, integration.urlPatterns) || "";
-                if (matchedPattern) {
-                    reason = `Found API URL pattern "${matchedPattern}"`;
+                if (isDocker) {
+                    // Specialized Dockerfile scanning: scan the exact full content
+                    matchedPattern = matchPatterns(contentRaw, integration.dockerPatterns) || "";
+                    if (matchedPattern) {
+                        reason = `Found deployment marker "${matchedPattern}" in ${fileName}`;
+                    }
                 }
                 else {
-                    matchedPattern = matchPatterns(content, integration.importPatterns) || "";
+                    // Standard source code checks
+                    matchedPattern = matchPatterns(content, integration.urlPatterns) || "";
                     if (matchedPattern) {
-                        reason = `Found SDK import pattern "${matchedPattern}"`;
+                        reason = `Found API URL pattern "${matchedPattern}"`;
                     }
                     else {
-                        matchedPattern = matchPatterns(content, integration.envPatterns) || "";
+                        matchedPattern = matchPatterns(content, integration.importPatterns) || "";
                         if (matchedPattern) {
-                            reason = `Found env var reference "${matchedPattern}"`;
+                            reason = `Found SDK import pattern "${matchedPattern}"`;
+                        }
+                        else {
+                            matchedPattern = matchPatterns(content, integration.envPatterns) || "";
+                            if (matchedPattern) {
+                                reason = `Found env var reference "${matchedPattern}"`;
+                            }
                         }
                     }
                 }

package/dist/constants.d.ts

@@ -25,6 +25,8 @@ export interface IntegrationDef {
     urlPatterns?: string[];
     importPatterns?: string[];
     envPatterns?: string[];
+    configPatterns?: string[];
+    dockerPatterns?: string[];
 }
 export declare const INTEGRATIONS: IntegrationDef[];
 export declare const SOURCE_EXTENSIONS: string[];

package/dist/constants.js

@@ -154,41 +154,73 @@ exports.INTEGRATIONS = [
         id: "aws",
         name: "AWS",
         importPatterns: ["boto3", "aws-sdk", "@aws-sdk"],
+        configPatterns: ["buildspec.yml", "samconfig.toml", "serverless.yml"],
         envPatterns: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION", "AWS_DEFAULT_REGION"],
+        dockerPatterns: ["public.ecr.aws", "amazonaws.com"],
     },
     {
         id: "azure",
         name: "Microsoft Azure",
         importPatterns: ["azure", "@azure"],
         urlPatterns: ["windows.net", "azure.com"],
+        configPatterns: ["azure-pipelines.yml"],
         envPatterns: ["AZURE_CLIENT_ID", "AZURE_TENANT_ID"],
+        dockerPatterns: ["mcr.microsoft.com", "azurecr.io"],
     },
     {
         id: "gcp",
         name: "Google Cloud",
         importPatterns: ["google-cloud", "@google-cloud"],
         urlPatterns: ["googleapis.com"],
+        configPatterns: ["app.yaml", "cloudbuild.yaml"],
         envPatterns: ["GOOGLE_APPLICATION_CREDENTIALS"],
+        dockerPatterns: ["gcr.io", "pkg.dev"],
     },
     // Hosting & Edge
     {
         id: "vercel",
         name: "Vercel",
         importPatterns: ["@vercel"],
+        configPatterns: ["vercel.json"],
         envPatterns: ["VERCEL_URL", "VERCEL_PROJECT_ID"],
     },
     {
         id: "netlify",
         name: "Netlify",
         importPatterns: ["@netlify"],
-        envPatterns: ["NETLIFY", "URL"],
+        configPatterns: ["netlify.toml"],
+        envPatterns: ["NETLIFY", "NETLIFY_AUTH_TOKEN"], // Removed generic URL
     },
     {
         id: "cloudflare",
         name: "Cloudflare",
         importPatterns: ["cloudflare", "@cloudflare"],
+        configPatterns: ["wrangler.toml"],
         envPatterns: ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"],
     },
+    {
+        id: "flyio",
+        name: "Fly.io",
+        configPatterns: ["fly.toml"],
+        dockerPatterns: ["flyio", "flyctl"],
+    },
+    {
+        id: "railway",
+        name: "Railway",
+        configPatterns: ["railway.json", "railway.toml"],
+        dockerPatterns: ["railwayapp"],
+    },
+    {
+        id: "render",
+        name: "Render",
+        configPatterns: ["render.yaml"],
+    },
+    {
+        id: "digitalocean",
+        name: "DigitalOcean",
+        configPatterns: ["app-spec.yaml", "digitalocean.yaml"],
+        dockerPatterns: ["digitalocean"],
+    },
     // Firebase
     {
         id: "firebase",

package/dist/prompts.js

@@ -8,7 +8,7 @@ exports.CODEBASE_ANALYSIS_SIGNATURE = (0, ax_1.f)()
     .output("projectOverview", ax_1.f.string("Project Overview & Context: Exhaustively describe all primary sub-services, their purpose, and what languages or frameworks power them."))
     .output("agentPersona", ax_1.f.string("Agent Persona / Role"))
     .output("techStack", ax_1.f.string("Tech Stack & Versions: List EVERY distinct language, library, database, and external API dependency used. WARNING: Do NOT guess frameworks based on assumptions or the presence of a package.json. You must explicitly scan the actual code files (e.g. imports in .py, .ts, .js) and dependency manifests (e.g. requirements.txt, go.mod) to determine the EXACT tech stack."))
-    .output("directoryStructure", ax_1.f.string("Directory Structure (The Map): Deeply map out all root folders, separating different sub-projects (frontend vs backend) and their specific structures."))
+    .output("directoryStructure", ax_1.f.string("Directory Structure (The Map): Deeply map out all root folders. CRITICAL: You MUST strictly represent the EXACT physical file and directory structure provided in the source context. Do NOT invent, extrapolate, or hallucinate conceptual directories (like 'client/' or 'server/') if they do not physically exist on disk. If you see scripts like 'build:client' or 'build:server' in a package.json, interpret them as Build Output pipelines (like SSR/SSG), NOT as physical source directories unless those directories literally exist."))
     .output("executionCommands", ax_1.f.string("Execution Commands: Exact terminal commands to run or build."))
     .output("codeStyleAndFormatting", ax_1.f.string("Code Style & Formatting: Language-specific formatting and strictly enforced linting rules."))
     .output("architectureAndDesignPatterns", ax_1.f.string("Architecture & Design Patterns: Detailed cross-service logical flow, API boundaries, and system design logic."))
@@ -32,7 +32,7 @@ exports.COMPILE_CONVENTIONS_SIGNATURE = (0, ax_1.f)()
     .input("projectOverview", ax_1.f.string("Project Overview & Context."))
     .input("agentPersona", ax_1.f.string("Agent Persona / Role."))
     .input("techStack", ax_1.f.string("Tech Stack & Versions."))
-    .input("directoryStructure", ax_1.f.string("Directory Structure (The Map)."))
+    .input("directoryStructure", ax_1.f.string("Directory Structure (The Map). CRITICAL: Maintain the exact PHYSICAL file and directory structure produced by the analyzer. Do NOT invent conceptual boundaries (like client/ or server/) if they are not in the provided map."))
     .input("executionCommands", ax_1.f.string("Execution Commands."))
     .input("codeStyleAndFormatting", ax_1.f.string("Code Style & Formatting."))
     .input("architectureAndDesignPatterns", ax_1.f.string("Architecture & Design Patterns."))
@@ -56,7 +56,7 @@ exports.EXTRACT_AGENTS_SECTIONS_SIGNATURE = (0, ax_1.f)()
     .input("awarenessContext", ax_1.f.string("Deterministically detected framework/architecture constraints. AUTHORITATIVE — do not contradict. If OpenClaw orchestrator is present, include OpenClaw Runtime section. Show version certainty for each framework. Include Framework References when web refs are available."))
     .output("projectOverview", ax_1.f.string("Comprehensive description of the project: what it does, its tech stack, its primary languages, and its overall purpose and functionality."))
     .output("techStack", ax_1.f.string("Explicit and exhaustive list of supported languages, frameworks, UI libraries, backend runtimes, and tools used in the repository. Annotate what each technology is used for (e.g., 'X Framework for UI', 'Y Language for REST Services')."))
-    .output("architecture", ax_1.f.string("Deep mapping of where things live: directory layout, key modules, entry points, and their responsibilities. You MUST generate an ASCII diagram showing the architecture, module relationships, and sub-services. Break down complex monorepos explicitly (e.g., separating frontend code vs backend code)."))
+    .output("architecture", ax_1.f.string("Deep mapping of where things live: directory layout, key modules, entry points, and their responsibilities. You MUST generate an ASCII diagram showing the strict PHYSICAL file architecture. CRITICAL: Do NOT invent conceptual directories like 'client/' or 'server/' if they do not exist on disk. Rely solely on the provided conventions Markdown. Build targets (like SSR/SSG scripts) are behaviors, not physical source folders."))
     .output("codeStyle", ax_1.f.string("Granular coding standards observed: language version, formatting, naming conventions, import ordering, type-hinting rules, preferred patterns vs anti-patterns. Explicitly mention how different stacks in a monorepo communicate (e.g., REST, GraphQL, etc.) and how proprietary or 3rd-party external APIs are wrapped or invoked. Provide concrete examples from the codebase. All code blocks must be properly opened AND closed with triple backticks."))
     .output("antiPatternsAndRestrictions", ax_1.f.string("Specific anti-patterns and 'NEVER do this' rules the AI must strictly avoid."))
     .output("databaseAndState", ax_1.f.string("Guidelines on how data and state should flow through the application, including databases, external API data syncing, or state managers."))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thelogicatelier/sylva",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Auto-generate AGENTS.md for your repository using Ax-LLM. Analyze the structural backbone, data flow, and day-to-day coding conventions natively.",
   "main": "dist/index.js",
   "bin": {
@@ -64,4 +64,4 @@
     "prettier": "^3.8.1",
     "typescript-eslint": "^8.56.1"
   }
-}
+}