codeaura-embedded-runtime-agent 0.1.0

package/.env.example

@@ -0,0 +1,4 @@
+# CodeAura API Configuration
+# The API endpoint is pre-configured in the agent
+# You only need to provide your API key
+API_KEY=your-api-key-here

package/.eslintignore

@@ -0,0 +1,3 @@
+node_modules/*
+examples/*
+*.min.js

package/.eslintrc

@@ -0,0 +1,97 @@
+{
+    //     ╔═╗╔═╗╦    ╦╔╗╔╔╦╗┬─┐┌─┐
+    //     ║╣ ╚═╗║    ║║║║ ║ ├┬┘│
+    //    o╚═╝╚═╝╩═╝╩╝╚╝ ╩ ┴└─└─┘
+    // A set of basic code conventions designed to encourage quality and consistency
+    // across your CodeAura Embedded Runtime Agent code base. These rules are checked
+    // automatically any time you run `npm test`.
+    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+    // For more information about any of the rules below, check out the relevant
+    // reference page on eslint.org. For example, to get details on "no-sequences",
+    // you would visit `http://eslint.org/docs/rules/no-sequences`.
+    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+    "env": {
+        "node" : true,
+        "es6" : true
+    },
+
+    "parserOptions": {
+        "ecmaVersion": 2022,
+        "sourceType": "module"
+    },
+
+    "globals": {
+        "Promise": true
+    },
+
+    "rules": {
+        "strict": 1,
+        "block-scoped-var": ["error"],
+        "callback-return": ["error", ["done", "proceed", "next", "onwards", "callback", "cb"]],
+        "camelcase": ["warn", {"properties":"never"}],
+        "comma-style": ["warn", "last"],
+        "curly": ["warn"],
+        "eqeqeq": ["off"],
+        "eol-last": ["off"],
+        "handle-callback-err": ["error"],
+        "indent": ["warn", 4, {
+            "SwitchCase": 1,
+            "MemberExpression": "off",
+            "FunctionDeclaration": {"body":1, "parameters":"off"},
+            "FunctionExpression": {"body":1, "parameters":"off"},
+            "CallExpression": {"arguments":"off"},
+            "ArrayExpression": 1,
+            "ObjectExpression": 1,
+            "ignoredNodes": ["ConditionalExpression"]
+        }],
+        "no-dupe-keys": ["error"],
+        "no-duplicate-case": ["error"],
+        "no-extra-semi": ["warn"],
+        "no-labels": ["error"],
+        "no-mixed-spaces-and-tabs": [2, "smart-tabs"],
+        "no-redeclare": ["warn"],
+        "no-return-assign": ["error", "always"],
+        "no-sequences": ["error"],
+        "no-trailing-spaces": ["warn"],
+        "no-undef": ["warn"],
+        "no-unexpected-multiline": ["warn"],
+        "no-unreachable": ["warn"],
+        "no-unused-vars": ["warn", {"caughtErrors":"all", "caughtErrorsIgnorePattern": "^unused($|[A-Z].*$)", "argsIgnorePattern": "^unused($|[A-Z].*$)", "varsIgnorePattern": "^unused($|[A-Z].*$)" }],
+        "no-use-before-define": ["error", {"functions":false}],
+        "one-var": ["warn", "always"],
+        "prefer-arrow-callback": ["warn", {"allowNamedFunctions":true}],
+        "quotes": ["warn", "double", {"avoidEscape":false, "allowTemplateLiterals":true}],
+        "semi": ["warn", "always"],
+        "semi-spacing": ["warn", {"before":false, "after":true}],
+        "semi-style": ["warn", "last"],
+        "comma-dangle": ["error", "never"],
+        "multiline-ternary": ["error", "always-multiline"],
+        "padding-line-between-statements": [
+            "warn",
+            // Newline BEFORE variable declarations (unless top of block)
+            { "blankLine": "always", "prev": "*", "next": ["const", "let", "var"] },
+
+            // Allow grouped variable declarations
+            { "blankLine": "any", "prev": ["const", "let", "var"], "next": ["const", "let", "var"] },
+
+            // Newline AFTER variable declarations
+            { "blankLine": "always", "prev": ["const", "let", "var"], "next": "*" },
+            { "blankLine": "always", "prev": "*", "next": "return" }
+          ],
+        "brace-style": ["warn", "1tbs", {
+            "allowSingleLine": false
+            }
+        ],
+        "object-curly-newline": ["error", {
+            "multiline": true,
+            "consistent": true
+            }
+        ],
+        "function-call-argument-newline": ["warn", "consistent"],
+        "space-before-blocks": "warn",
+        "no-multiple-empty-lines": ["error", {
+            "max": 1
+        }]
+    }
+}

package/CLAUDE.md

@@ -0,0 +1,210 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Core Development
+- **Run tests**: `npm test`
+- **Node.js version**: >=14.0.0 (specified in package.json engines)
+
+### Local Development Setup
+- Install as local dependency: `npm install /path/to/codeaura-embedded-runtime-agent`
+- Integration with Sails.js application via `config/bootstrap.js`
+- Set environment variable:
+  - `API_KEY` - Your CodeAura API key (required)
+- The API endpoint is pre-configured in the agent (`https://api.codeaura.dev/api/v1/runtime-agent/events`)
+
+## Architecture Overview
+
+This is a lightweight runtime execution tracer for JavaScript applications, with initial support for Sails.js (Node.js). The agent captures real execution behavior from a running application and sends it to the CodeAura platform for analysis.
+
+### Core Systems
+
+**Module Organization (src/)**
+- `agent/` - Main agent entry point and lifecycle management
+- `instrumentation/` - Function wrapping and HTTP interception logic
+- `framework/` - Framework-specific hooks (Sails.js in V1)
+- `core/` - Universal event format, transport, and buffering
+- `config/` - Agent configuration management
+- `utils/` - Logging and utility functions
+
+**Agent Architecture**
+- **Agent** - Main entry point with singleton pattern
+- **Config** - Configuration management with safe defaults and validation
+- **Logger** - Internal logging that never crashes the host application
+- **EventSchema** - Universal event format for all captured executions
+- **Transport** - Event delivery via HTTP/HTTPS to CodeAura API
+- **Buffer** - In-memory event buffering before transmission
+
+**Runtime Instrumentation**
+- Function wrapping for controllers and helpers
+- HTTP request interception
+- Real-time execution event capture
+- Timing, metadata, and error recording
+- Zero-impact on host application behavior
+
+### Key Design Principles
+
+**Non-Intrusive Operation**
+- Agent must never crash the host application
+- Minimal overhead (< 5% performance impact)
+- No debuggers or breakpoints required
+- No code modification needed in host application
+
+**Extensibility for Future Versions**
+- Modular design supports future frameworks (Express, NestJS, Fastify)
+- Architecture ready for multi-language support (Python planned)
+- Event format designed to evolve incrementally
+
+### Naming Conventions
+
+**Files and Directories**: camelCase (`functionWrapper.js`, `httpTransport.js`)
+**JavaScript**: camelCase for variables/functions, snake_case for config keys
+**Classes**: PascalCase (`Agent`, `Config`, `Logger`, `EventSchema`)
+**Module Exports**: Singleton pattern where applicable
+
+### Development Guidelines
+
+**Module Development**
+- Follow singleton pattern for core services (Agent, Logger)
+- Use class-based architecture for main components
+- Implement proper error handling that never crashes host app
+- Include comprehensive JSDoc documentation
+- Keep V1 simple and focused - defer advanced features to future versions
+
+**Error Handling**
+- All errors must be caught and logged internally
+- Never let agent errors propagate to host application
+- Use try/catch in all critical paths
+- Log errors with stack traces using `logger.errorWithStack()`
+
+**Configuration Management**
+- Provide safe defaults for all settings
+- Support environment variable overrides
+- Validate configuration on initialization
+- Merge user config with defaults safely
+
+**Event Capture**
+- Use minimal event format (V1)
+- Include only essential metadata
+- Keep event schema extensible for future versions
+- Buffer events before transmission
+
+### Key Dependencies
+
+**Core Runtime**: Node.js >=14.0.0
+**HTTP Client**: axios ^1.6.0
+**Framework Support**: Sails.js (V1), more frameworks planned
+**Transport**: HTTP/HTTPS to CodeAura API
+
+When modifying this codebase, always follow the established patterns for non-intrusive instrumentation, singleton management, and defensive error handling. The architecture emphasizes simplicity, safety, and extensibility.
+
+
+## Code Style & Linting Rules
+
+### ESLint Configuration
+All generated code must comply with the following linting rules:
+
+**Indentation & Formatting:**
+- Use 4-space indentation (not 2 or tabs)
+- Switch cases should be indented 1 level from switch statement
+- Use "1tbs" brace style (opening brace on same line, closing brace on new line)
+- No single-line blocks allowed - always use multiline format
+- Add space before opening braces
+
+**Variable Declarations:**
+- Use `one-var` style - declare multiple variables with single `var`/`let`/`const`
+- Add blank lines before and after variable declarations
+- Group variable declarations together when possible
+- Handle unused variables with `unused` prefix (e.g., `unusedErr`, `unusedData`)
+- Always define the variables at the top, outside the try/catch block except for variables used for loops
+- When defining the variables, set the values to null, or empty string, depending on the variable use - the initialization of the variable is always done within the try/catch block unless you are initializing to a constant
+
+**Quotes & Semicolons:**
+- Use double quotes for all strings
+- Allow template literals when needed
+- Always use semicolons at end of statements
+- Add space after semicolons, no space before
+- No trailing commas in objects/arrays
+
+**Functions & Callbacks:**
+- Use camelCase for function names (no underscores in properties)
+- Prefer arrow functions but allow named functions
+- Handle callback errors properly - use callback names: `done`, `proceed`, `next`, `onwards`, `callback`, `cb`
+- Functions can be used before definition
+
+**Control Flow:**
+- Always use curly braces for if/else/for/while blocks
+- Use multiline ternary operators when complex
+- No return assignments
+- No sequences (comma operator)
+- Equality checks: `==` and `!=` are allowed (eqeqeq is off)
+
+**Code Quality:**
+- Use strict mode
+- Block-scoped variables only
+- No duplicate keys in objects
+- No duplicate cases in switch statements
+- No unreachable code
+- No undefined variables (warnings only)
+- No mixed spaces and tabs (smart-tabs allowed)
+- No trailing spaces
+- No extra semicolons
+
+**Spacing & Layout:**
+- Add blank line before return statements
+- Add blank lines before and after variable declarations
+- Consistent newlines in function call arguments
+- Multiline object literals should have consistent newlines
+- No unexpected multiline statements
+
+**Error Handling:**
+- Always handle callback errors
+- Use proper callback return patterns
+
+## Control Flow Rules
+
+### Mandatory Else Conditions
+**All `if` statements must have a corresponding `else` block** except if the `else` block is empty.
+
+## Module Development Rules
+
+### Avoid use of inline and nested functions
+Avoid using inline or nested functions in modules unless absolutely necessary. Any such occurrences should instead be replaced by the creation of utility helpers or separate module functions.
+
+### Single Responsibility Modules
+Modules should follow the Single Responsibility Principle by focusing on a single, well-defined task. However, avoid splitting functionality into excessively simplistic modules that reduce clarity or cohesion.
+
+### Class-Based Components
+For main components (Agent, Config, Logger, etc.), use class-based architecture with proper encapsulation and clear public APIs.
+
+## Additional instructions
+- Avoid adding inline comments in the code
+- For all try/catch blocks, in the catch blocks, display the error with stack trace as `logger.errorWithStack(message, error);`
+- Agent must never crash the host application - defensive error handling is critical
+
+## Code Structure & Best Practices
+
+### Variable Definition
+- Always define all your variables at the start of the function outside the try/catch block.
+- Initialize variables to null or empty values, then assign actual values inside try/catch.
+
+### Singleton Pattern
+- Use singleton pattern for core services (Agent, Logger)
+- Export factory functions that manage singleton instances
+- Provide both getInstance() and create new instance methods
+
+### Defensive Programming
+- Assume any operation can fail
+- Wrap all critical sections in try/catch
+- Log errors but never throw exceptions that could crash host app
+- Validate all inputs and configuration
+
+## V1 Scope and Limitations
+
+This is Version 1 - a proof of concept focused on Sails.js support:
+- Keep implementation simple and focused
+- Defer advanced features (retries, persistence, multi-framework support) to future versions
+- Prioritize stability and minimal overhead over feature completeness
+- Document TODOs clearly for future enhancements

package/README.md

@@ -0,0 +1,234 @@
+# CodeAura Embedded Runtime Agent
+
+> **Lightweight runtime execution tracer for JavaScript applications**
+> *Initial support: Sails.js (Node.js)*
+
+---
+
+## 📌 Overview
+
+**CodeAura Embedded Runtime Agent** is a lightweight runtime instrumentation agent designed to capture **real execution behavior** from a running JavaScript application and send it to the **CodeAura platform** for analysis, visualization, and documentation.
+
+Unlike traditional debugging or profiling tools, the agent:
+
+* works **without breakpoints or debuggers**
+* runs **inside the application process**
+* works even when the application and CodeAura run on **different servers**
+
+The first version (V1) focuses on **Sails.js applications**, while being architected to support **other frameworks and languages in future versions**.
+
+---
+
+## 🎯 Goals (V1)
+
+The main objectives of this first version are:
+
+* Capture **runtime execution events** from a real Sails.js application
+* Observe how controllers and helpers are executed in production-like conditions
+* Send structured execution events to the CodeAura API
+* Prove that the approach is **technically viable, stable, and low-overhead**
+
+This version is intentionally **simple and focused**.
+
+---
+
+## 🚫 Non-goals (V1)
+
+To keep the scope realistic, V1 **does not aim to**:
+
+* Support multiple frameworks (Express, NestJS, Fastify, etc.)
+* Support multiple languages (Python, Java, etc.)
+* Perform deep database-level or infrastructure tracing
+* Provide advanced retry, buffering, or persistence mechanisms
+* Act as a full observability or APM solution
+
+All of the above are planned for future versions.
+
+---
+
+## 🧠 How It Works
+
+At a high level:
+
+1. The agent is installed as a Node.js dependency inside a Sails.js project
+2. During application startup, the agent:
+
+   * hooks into the Sails lifecycle
+   * wraps selected runtime functions (controllers, helpers)
+3. When the application runs normally:
+
+   * execution events are captured in real time
+   * timing, metadata, and errors are recorded
+4. Events are sent via HTTP/HTTPS to the CodeAura API
+
+No debugger, no code modification, no shared runtime required.
+
+---
+
+## 🏗 High-Level Architecture
+
+```
+┌───────────────────────────┐
+│ Sails.js Application      │
+│                           │
+│  ┌─────────────────────┐  │
+│  │ Runtime Agent       │  │
+│  │ (installed module)  │  │
+│  └─────────────────────┘  │
+│            │              │
+│            ▼              │   HTTP/HTTPS
+└─────────▶ Events ───────────────────▶ CodeAura API
+              (JSON)
+```
+
+---
+
+## 📦 Project Structure (V1)
+
+```text
+codeaura-embedded-runtime-agent/
+├── src/
+│   ├── agent/
+│   │   └── Agent.js                # Main agent entry point
+│   │
+│   ├── instrumentation/
+│   │   └── nodejs/
+│   │       ├── functionWrapper.js  # Function wrapping logic
+│   │       └── httpInterceptor.js  # HTTP request interception
+│   │
+│   ├── framework/
+│   │   └── nodejs/
+│   │       └── sails/
+│   │           └── sailsHook.js     # Sails.js-specific hook
+│   │
+│   ├── core/
+│   │   ├── events/
+│   │   │   └── EventSchema.js       # Universal event format
+│   │   ├── transport/
+│   │   │   └── httpTransport.js     # Event delivery
+│   │   └── buffer/
+│   │       └── memoryBuffer.js      # In-memory buffering
+│   │
+│   ├── config/
+│   │   └── config.js                # Agent configuration
+│   │
+│   └── utils/
+│       └── logger.js                # Internal logging
+│
+├── README.md
+└── package.json
+```
+
+---
+
+## 📊 Event Format (V1)
+
+Events are sent as simple JSON objects:
+
+```json
+{
+  "type": "controller",
+  "name": "user/create",
+  "framework": "sailsjs",
+  "language": "nodejs",
+  "timestamp": "2026-01-07T12:45:02.501Z",
+  "durationMs": 12,
+  "meta": {
+    "route": "POST /user",
+    "status": 200
+  }
+}
+```
+
+This format is intentionally minimal and will evolve over time.
+
+---
+
+## ⚙️ Installation
+
+```bash
+npm install codeaura-embedded-runtime-agent
+```
+
+---
+
+## 🔌 Integration with Sails.js
+
+Add the agent initialization during the Sails bootstrap phase:
+
+```js
+// config/bootstrap.js
+module.exports.bootstrap = async function () {
+  require("codeaura-embedded-runtime-agent").init(sails);
+};
+```
+
+That’s it.
+No changes to controllers, helpers, or models are required.
+
+---
+
+## 🛠 Configuration
+
+The agent requires minimal configuration. You only need to provide your API key:
+
+```js
+module.exports = {
+  apiKey: "YOUR_API_KEY"
+};
+```
+
+Or use environment variable:
+```bash
+export API_KEY="YOUR_API_KEY"
+```
+
+Optional settings:
+```js
+module.exports = {
+  apiKey: "YOUR_API_KEY",
+  enabled: true  // Set to false to disable the agent (default: true)
+};
+```
+
+**Note:** The CodeAura API endpoint is pre-configured in the agent and does not need to be specified.
+
+---
+
+## ⚠️ Performance & Safety
+
+* The agent adds **minimal overhead** (typically < 5%)
+* Events are buffered in memory before being sent
+
+---
+
+## 🧩 Extensibility & Future Support
+
+Although V1 only supports **Sails.js on Node.js**, the architecture anticipates:
+
+* Other Node.js frameworks (Express, NestJS, Fastify)
+* Other languages (Python planned)
+* Advanced buffering and retry strategies
+* Security features (masking, anonymization)
+* Deeper execution graphs and correlations
+
+These will be introduced incrementally in future versions.
+
+---
+
+## ✅ Success Criteria (V1)
+
+This version is considered successful if:
+
+* A real Sails.js application can be instrumented
+* Controllers and helpers are captured automatically
+* Execution events reach CodeAura reliably
+* The application behavior remains unchanged
+* The codebase stays clean, readable, and maintainable
+
+---
+
+## 📌 Status
+
+**Version:** 0.1.0
+**Status:** Proof of Concept (V1)