refactor: rename DiagnosticAgent → ArgusAgent across entire codebase

- Rename src/diagnostic-agent.ts → src/argus-agent.ts
- Rename tests/diagnostic-agent*.test.ts → tests/argus-agent*.test.ts
- Replace all DiagnosticAgent class/type references with ArgusAgent
- Update all import paths from diagnostic-agent to argus-agent
- Update Symbol.for("diagnostic-agent.patched") → "argus-agent.patched"
- Update README, CHANGELOG, CONTRIBUTING, DEMO.md

Aligns the public API with the package name (argus).
All 508 tests pass, 0 TS errors, 0 ESLint warnings, Prettier clean.

Author: sharon77242

CHANGELOG.md

@@ -26,7 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Architecture — God object split**: Extracted three cohesive modules from the 1 109-line
   `diagnostic-agent.ts`:
   - `src/internal/profile-factory.ts` — `buildAgentProfile()` contains all preset-resolution
-    and builder-wiring logic for `DiagnosticAgent.createProfile()`.
+    and builder-wiring logic for `ArgusAgent.createProfile()`.
   - `src/internal/query-handler.ts` — `createQueryHandler()` factory produces the per-query
     processing closure (adaptive sampling → query analysis → slow-query check → aggregation).
   - `src/internal/console-logger.ts` — `installConsoleLogger()` registers formatted console
@@ -44,7 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 #### Core agent
-- `DiagnosticAgent` fluent builder with two entry points: `create()` (manual) and
+- `ArgusAgent` fluent builder with two entry points: `create()` (manual) and
   `createProfile()` (preset-based).
 - Zero-overhead global kill-switch via `DIAGNOSTIC_AGENT_ENABLED=false` — `.start()` becomes
   a no-op with no timer, subscription, or memory overhead.
@@ -54,7 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Three environment presets: `prod`, `dev`, `test`.
 - Three app-type presets: `web`, `db`, `worker` (composable as an array).
 - `'auto'` mode — scans `package.json` dependencies and infers the correct preset.
-- `DiagnosticAgent.detectAppTypes()` standalone detector.
+- `ArgusAgent.detectAppTypes()` standalone detector.
 
 #### Instrumentation
 - `node:diagnostics_channel`-based query tracing for 14 DB drivers: `pg`, `mysql2`, `mssql`,

CONTRIBUTING.md

@@ -56,7 +56,7 @@ pnpm lint:fix         # auto-fix what's fixable
 The agent is structured in five layers:
 
 ```
-DiagnosticAgent (fluent builder + event bus)
+ArgusAgent (fluent builder + event bus)
   │
   ├── Profiling          — runtime observation, crash interception, source maps
   │     RuntimeMonitor    event-loop lag, heap growth (accumulated model)
@@ -110,7 +110,7 @@ DB driver interception uses `node:diagnostics_channel` (the official Node.js obs
 
 ### CrashGuard flush before process.exit
 
-When `DiagnosticAgent.wireGuards()` creates `CrashGuard`, it passes `() => this.stop()` as the `beforeExit` callback. On an `uncaughtException`:
+When `ArgusAgent.wireGuards()` creates `CrashGuard`, it passes `() => this.stop()` as the `beforeExit` callback. On an `uncaughtException`:
 1. The crash event is emitted synchronously (in-process listeners get it).
 2. `beforeExit()` is awaited (max 2 s) so the OTLP exporter can flush.
 3. `process.exit(1)` runs only after the flush or the deadline, whichever comes first.
@@ -175,7 +175,7 @@ This section tracks planned monitoring capabilities — what's already shipped,
 | Cache hit-rate monitoring | `CacheMonitor` | Sliding-window hit rate, fires `cache-degraded` |
 | Query plan analysis (EXPLAIN) | `ExplainAnalyzer` | User-supplied executor, per-pattern cooldown |
 | DNS resolution monitoring | `DnsMonitor` | `dns.lookup` intercept, `slow-dns` events |
-| Adaptive sampling | `AdaptiveSampler` | Token-bucket per category, wired in `DiagnosticAgent` |
+| Adaptive sampling | `AdaptiveSampler` | Token-bucket per category, wired in `ArgusAgent` |
 | OTLP-compatible export (no mTLS) | `OTLPCompatibleExporter` | Plain http/https, optional bearer token |
 
 ---

README.md

@@ -87,13 +87,13 @@ This package ships a **dual build**: ESM and CommonJS. Node.js picks the right f
 
 ```js
 // ✅ ESM project (type:module or .mjs)
-import { DiagnosticAgent } from 'argus';
+import { ArgusAgent } from 'argus';
 
 // ✅ CommonJS project — require() works directly
-const { DiagnosticAgent } = require('argus');
+const { ArgusAgent } = require('argus');
 
 // ✅ CommonJS project — dynamic import also works
-const { DiagnosticAgent } = await import('argus');
+const { ArgusAgent } = await import('argus');
 ```
 
 ---
@@ -109,7 +109,7 @@ npm install argus
 Then import from the compiled entry point:
 
 ```typescript
-import { DiagnosticAgent } from 'argus';
+import { ArgusAgent } from 'argus';
 ```
 
 ### Building from source (Node ≥ 22.6, contributors only)
@@ -152,12 +152,12 @@ dist/
 
 ```typescript
 // Compiled npm package
-import { DiagnosticAgent } from 'argus';
+import { ArgusAgent } from 'argus';
 
 // Or if running source directly (Node 22.6+)
-// import { DiagnosticAgent } from './packages/agent/src/index.ts';
+// import { ArgusAgent } from './packages/agent/src/index.ts';
 
-const agent = await DiagnosticAgent.createProfile({
+const agent = await ArgusAgent.createProfile({
   environment: 'prod',   // or 'dev' | 'test'
   appType: ['web', 'db'],
 }).start();
@@ -195,7 +195,7 @@ See [`quotes-demo-app/README.md`](quotes-demo-app/README.md) for the full setup
 `createProfile` returns a pre-configured builder instance wired for your environment and app type. Call `.start()` to initialize all subsystems.
 
 ```typescript
-const agent = await DiagnosticAgent.createProfile({
+const agent = await ArgusAgent.createProfile({
   environment: 'prod',        // 'dev' | 'test' | 'prod'
   appType: ['web', 'db'],     // single string or array — modules are unioned
   enabled: true,              // overridden by DIAGNOSTIC_AGENT_ENABLED env-var
@@ -227,21 +227,21 @@ Each `.with*()` call is **idempotent** — combining types never double-register
 
 ```typescript
 // Express API + background job runner
-DiagnosticAgent.createProfile({ appType: ['web', 'worker'] });
+ArgusAgent.createProfile({ appType: ['web', 'worker'] });
 
 // Worker that queries databases directly
-DiagnosticAgent.createProfile({ appType: ['db', 'worker'] });
+ArgusAgent.createProfile({ appType: ['db', 'worker'] });
 
 // Monolith — full coverage
-DiagnosticAgent.createProfile({ appType: ['web', 'db', 'worker'] });
+ArgusAgent.createProfile({ appType: ['web', 'db', 'worker'] });
 ```
 
 ### Auto-Detection
 
 Leave `appType` unset (or set it to `'auto'`) and the agent will scan your `package.json` dependencies to infer the correct profile:
 
 ```typescript
-const agent = await DiagnosticAgent.createProfile({
+const agent = await ArgusAgent.createProfile({
   environment: 'prod',
   // appType: 'auto' is the default
 }).start();
@@ -252,7 +252,7 @@ const agent = await DiagnosticAgent.createProfile({
 You can also call the detector standalone:
 
 ```typescript
-const result = DiagnosticAgent.detectAppTypes('./my-service');
+const result = ArgusAgent.detectAppTypes('./my-service');
 // { types: ['web', 'db'], matches: { web: ['express', 'cors'], db: ['pg', 'ioredis'], worker: [] } }
 ```
 
@@ -274,10 +274,10 @@ const result = DiagnosticAgent.detectAppTypes('./my-service');
 For maximum control, compose the agent manually using the fluent builder:
 
 ```typescript
-import { DiagnosticAgent } from 'argus';
+import { ArgusAgent } from 'argus';
 import fs from 'node:fs';
 
-const agent = await DiagnosticAgent.create()
+const agent = await ArgusAgent.create()
   .withSourceMaps('./dist')                          // Source-map resolution for stack traces
   .withRuntimeMonitor({ eventLoopThresholdMs: 50 }) // Event loop lag + memory leak detection
   .withInstrumentation({ autoPatching: true })       // 16 DB drivers via diagnostics_channel
@@ -468,7 +468,7 @@ Requires `.withSourceMaps()`.
 
 ## Events Reference
 
-The agent is an `EventEmitter`. All events are emitted on the `DiagnosticAgent` instance:
+The agent is an `EventEmitter`. All events are emitted on the `ArgusAgent` instance:
 
 | Event | Payload | When |
 |---|---|---|
@@ -527,7 +527,7 @@ agent.on('pool-exhaustion', (event) => {
 ```
 
 > [!NOTE]
-> `DiagnosticAgent` calls `setMaxListeners(0)` internally — you can attach as many listeners as needed without triggering Node's memory leak warning.
+> `ArgusAgent` calls `setMaxListeners(0)` internally — you can attach as many listeners as needed without triggering Node's memory leak warning.
 
 ---
 
@@ -557,8 +557,8 @@ All thresholds can be overridden without code changes, making the agent CI/CD an
 
 | Method | Prod Safe? | Resource Impact | Description |
 |---|---|---|---|
-| `DiagnosticAgent.createProfile(config)` | ✅ Yes | N/A | Pre-configured instance from env/app presets |
-| `DiagnosticAgent.create()` | ✅ Yes | N/A | Unconfigured fluent builder |
+| `ArgusAgent.createProfile(config)` | ✅ Yes | N/A | Pre-configured instance from env/app presets |
+| `ArgusAgent.create()` | ✅ Yes | N/A | Unconfigured fluent builder |
 | `.withSourceMaps(dir?)` | ✅ Yes | Very Low | Source-map resolution for minified stack traces |
 | `.withRuntimeMonitor(opts?)` | ✅ Yes | Low | Event loop lag + memory leak detection |
 | `.withCrashGuard()` | ✅ Yes | Very Low | Intercepts `uncaughtException`; emits event for `unhandledRejection` |
@@ -617,7 +617,7 @@ Telemetry is exported over **mTLS** (Mutual TLS) — both client and server cert
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
-│                        DiagnosticAgent                            │  ← Fluent builder / event bus
+│                        ArgusAgent                            │  ← Fluent builder / event bus
 ├──────────────────┬─────────────────────────┬─────────────────────┤
 │ Profiling        │  Instrumentation         │  Analysis           │
 │ ──────────────── │  ─────────────────────  │  ─────────────────  │
@@ -800,7 +800,7 @@ docker compose -f docker-compose.jaeger.yml up -d
 Then point the agent at it:
 
 ```typescript
-const agent = await DiagnosticAgent.createProfile({ environment: 'dev', appType: ['web', 'db'] })
+const agent = await ArgusAgent.createProfile({ environment: 'dev', appType: ['web', 'db'] })
   .withExporter({ endpointUrl: 'http://localhost:4318/v1/traces' })   // no TLS needed locally
   .start();
 ```

packages/agent/src/diagnostic-agent.ts packages/agent/src/argus-agent.tspackages/agent/src/diagnostic-agent.ts renamed to packages/agent/src/argus-agent.ts

@@ -60,7 +60,7 @@ import { createQueryHandler } from "./internal/query-handler.ts";
 import { installConsoleLogger, type DebugListener } from "./internal/console-logger.ts";
 
 // WeakMap-based private storage for license claims — avoids exposing internal field on agent
-const licenseClaims = new WeakMap<DiagnosticAgent, LicenseClaims>();
+const licenseClaims = new WeakMap<ArgusAgent, LicenseClaims>();
 
 export function shouldExport(eventType: string, claims: LicenseClaims | null): boolean {
   if (!claims) return false; // free mode: local EventEmitter only, no OTLP export
@@ -92,7 +92,7 @@ export interface AgentProfileConfig {
  *
  * @example
  * ```ts
- * const agent = await DiagnosticAgent.create()
+ * const agent = await ArgusAgent.create()
  *   .withSourceMaps('./dist')
  *   .withRuntimeMonitor({ eventLoopThresholdMs: 50 })
  *   .withInstrumentation()
@@ -103,7 +103,7 @@ export interface AgentProfileConfig {
  * agent.stop();
  * ```
  */
-export class DiagnosticAgent extends EventEmitter {
+export class ArgusAgent extends EventEmitter {
   // ── configuration captured by the builder ──
   private globallyDisabled = false;
   private sourceMapDir: string | null = null;
@@ -153,7 +153,7 @@ export class DiagnosticAgent extends EventEmitter {
   // Listeners added by useConsoleLogger — kept so they can be removed on stop().
   private debugListeners: DebugListener[] = [];
 
-  // Private constructor — use DiagnosticAgent.create()
+  // Private constructor — use ArgusAgent.create()
   private constructor() {
     super();
     // High-frequency events (query, http, fs, log) may have many listeners
@@ -164,8 +164,8 @@ export class DiagnosticAgent extends EventEmitter {
   /**
    * Entry point — returns a fresh builder instance.
    */
-  public static create(): DiagnosticAgent {
-    return new DiagnosticAgent();
+  public static create(): ArgusAgent {
+    return new ArgusAgent();
   }
 
   /**
@@ -179,13 +179,13 @@ export class DiagnosticAgent extends EventEmitter {
   }
 
   /**
-   * Generates a preconfigured DiagnosticAgent using highly optimized presets based on environment and application types.
+   * Generates a preconfigured ArgusAgent using highly optimized presets based on environment and application types.
    * Includes an `enabled` flag to return a true zero-overhead NoOp agent.
    *
    * Set `appType` to `'auto'` to auto-detect from `package.json` dependencies.
    */
-  public static createProfile(config: AgentProfileConfig): DiagnosticAgent {
-    const agent = new DiagnosticAgent();
+  public static createProfile(config: AgentProfileConfig): ArgusAgent {
+    const agent = new ArgusAgent();
 
     // Globally kill-switch the agent; .start() and .stop() will become 0-overhead.
     // Environment variables take precedence over the config object.
@@ -500,27 +500,24 @@ export class DiagnosticAgent extends EventEmitter {
       if (checkClockIntegrity(claims.tier, Date.now()) === "rollback") {
         this.emit(
           "error",
-          new Error("DiagnosticAgent: system clock anomaly detected — running in free mode"),
+          new Error("ArgusAgent: system clock anomaly detected — running in free mode"),
         );
       } else {
         licenseClaims.set(this, claims);
         this.emit(
           "info",
-          `DiagnosticAgent: tier=${claims.tier}, exp=${new Date(claims.exp * 1000).toISOString()}`,
+          `ArgusAgent: tier=${claims.tier}, exp=${new Date(claims.exp * 1000).toISOString()}`,
         );
       }
     } catch (err) {
       if ((err as Error).message === "EXPIRED") {
         writeExpirySignal("Renew at: https://argus.dev/billing");
         this.emit(
           "info",
-          "DiagnosticAgent: license expired — running in free mode. Renew at: https://argus.dev/billing",
+          "ArgusAgent: license expired — running in free mode. Renew at: https://argus.dev/billing",
         );
       } else {
-        this.emit(
-          "error",
-          new Error(`DiagnosticAgent: invalid license — ${(err as Error).message}`),
-        );
+        this.emit("error", new Error(`ArgusAgent: invalid license — ${(err as Error).message}`));
       }
     }
   }

packages/agent/src/index.ts

@@ -51,4 +51,4 @@ export * from "./licensing/clock-guard.ts";
 export * from "./licensing/expiry-signal.ts";
 
 // Top-level builder
-export * from "./diagnostic-agent.ts";
+export * from "./argus-agent.ts";

packages/agent/src/instrumentation/drivers/patch-utils.ts

@@ -49,7 +49,7 @@ export interface PatchRecord {
 
 export const activePatches: PatchRecord[] = [];
 
-export const PATCHED_SYMBOL = Symbol.for("diagnostic-agent.patched");
+export const PATCHED_SYMBOL = Symbol.for("argus-agent.patched");
 
 export function isAlreadyPatched(target: AnyTarget, methodName: string): boolean {
   return (target[methodName] as Record<symbol, unknown>)[PATCHED_SYMBOL] === true;

packages/agent/src/internal/console-logger.ts

@@ -1,7 +1,7 @@
 /**
- * Console debug logger for DiagnosticAgent.
+ * Console debug logger for ArgusAgent.
  *
- * Extracted from DiagnosticAgent to keep the main class focused on lifecycle.
+ * Extracted from ArgusAgent to keep the main class focused on lifecycle.
  * When DIAGNOSTIC_DEBUG=true the agent calls installConsoleLogger() once during
  * start() — all registered listeners are returned so the agent can remove them
  * on stop() without leaking event subscriptions.
@@ -19,7 +19,7 @@ export type DebugListener = [string, (...args: unknown[]) => void];
  * Registers coloured console output for every agent event and returns the
  * registered listener pairs so the caller can remove them on shutdown.
  *
- * @param emitter   The DiagnosticAgent instance (typed as EventEmitter to avoid circular dep).
+ * @param emitter   The ArgusAgent instance (typed as EventEmitter to avoid circular dep).
  * @param prefix    Log line prefix — default `"[DiagAgent]"`.
  * @param level     `"warn"` — anomalies/crashes/errors only.
  *                  `"verbose"` — also logs every query and HTTP request.

packages/agent/src/internal/profile-factory.ts

@@ -1,24 +1,24 @@
 /**
- * Profile factory — pure configuration logic for DiagnosticAgent.createProfile().
+ * Profile factory — pure configuration logic for ArgusAgent.createProfile().
  *
- * Kept separate from DiagnosticAgent to keep the main class focused on lifecycle
+ * Kept separate from ArgusAgent to keep the main class focused on lifecycle
  * and public API, not preset decision-making.
  */
 
-import type { DiagnosticAgent, AgentProfileConfig, AppType } from "../diagnostic-agent.ts";
+import type { ArgusAgent, AgentProfileConfig, AppType } from "../argus-agent.ts";
 import { detectAppTypes } from "../profiling/app-type-detector.ts";
 
 /**
  * Applies profile-based configuration to an already-constructed (but not yet started)
- * `DiagnosticAgent` instance. Calls only the agent's public builder methods.
+ * `ArgusAgent` instance. Calls only the agent's public builder methods.
  *
  * Separated from the static `createProfile()` factory so the decision logic can be
  * tested and reasoned about independently of the class lifecycle.
  *
- * @param agent  Fresh `DiagnosticAgent` instance (pre-disabled check done by caller).
+ * @param agent  Fresh `ArgusAgent` instance (pre-disabled check done by caller).
  * @param config Profile configuration from the caller.
  */
-export function buildAgentProfile(agent: DiagnosticAgent, config: AgentProfileConfig): void {
+export function buildAgentProfile(agent: ArgusAgent, config: AgentProfileConfig): void {
   const env = config.environment ?? "prod";
 
   // Resolve app types — 'auto' triggers package.json scanning
@@ -38,7 +38,7 @@ export function buildAgentProfile(agent: DiagnosticAgent, config: AgentProfileCo
         setImmediate(() => {
           agent.emit(
             "info",
-            "DiagnosticAgent: auto-detection found no recognized app type in package.json. " +
+            "ArgusAgent: auto-detection found no recognized app type in package.json. " +
               'Pass appType explicitly ("web" | "db" | "worker") to enable app-specific monitoring.',
           );
         });

packages/agent/src/internal/query-handler.ts

@@ -1,7 +1,7 @@
 /**
  * Query event handler factory.
  *
- * Extracts the dense per-query processing logic out of DiagnosticAgent so that
+ * Extracts the dense per-query processing logic out of ArgusAgent so that
  * wireInstrumentationEngine() becomes a lean wiring step, not a policy file.
  *
  * The handler is constructed once per agent start() and registered on the engine's

packages/agent/src/licensing/expiry-signal.ts

@@ -13,7 +13,7 @@ const SIGNAL_FILENAME = "diagnostic_agent_EXPIRED.txt";
  * Final fallback: writes to process.stderr (cannot be silenced without redirecting stderr).
  */
 export function writeExpirySignal(message: string): void {
-  const content = `[DiagnosticAgent] License expired — ${new Date().toISOString()}\n${message}\n`;
+  const content = `[ArgusAgent] License expired — ${new Date().toISOString()}\n${message}\n`;
 
   const candidates = [
     join(process.cwd(), SIGNAL_FILENAME),
@@ -31,5 +31,5 @@ export function writeExpirySignal(message: string): void {
   }
 
   // All file paths failed — stderr is the final fallback
-  process.stderr.write(`[DiagnosticAgent] EXPIRED: ${content}`);
+  process.stderr.write(`[ArgusAgent] EXPIRED: ${content}`);
 }