@voidwire/argus-send 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rudy Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# argus-send
+
+Send events to Argus observability platform from the command line.
+
+## Philosophy
+
+**Synchronous delivery** - Blocks until Argus confirms event captured, ensuring durability.
+
+**Config-aware** - Automatically reads API key from `~/.config/argus/config.toml`, no manual config needed.
+
+**Pipes JSON** - Accepts JSON data from other tools (gitignore-check, language-detect) via stdin.
+
+## Quick Start
+
+```bash
+# Tool event with agent observability fields
+argus-send --source momentum --type tool \
+  --hook PreToolUse \
+  --session-id "f10e9765-1999-456f-81c3-eb4c531ecee2" \
+  --tool-name Bash \
+  --tool-use-id "toolu_01ABC" \
+  --message "Bash: git status"
+
+# Session event
+argus-send --source momentum --type session \
+  --hook SessionStart \
+  --session-id "f10e9765-1999-456f-81c3-eb4c531ecee2" \
+  --message "Session started: argus (active)"
+
+# Pipe from another tool
+gitignore-check . | argus-send --source llcli-tools --type tool --stdin
+```
+
+## Installation
+
+```bash
+cd packages/argus-send
+bun link
+```
+
+Now `argus-send` is available globally.
+
+## Usage
+
+```
+argus-send --source <name> --type <event-type> [options]
+```
+
+### Required Arguments
+
+- `--source <name>` - Source name (e.g., "llcli-tools", "momentum")
+- `--type <event-type>` - Event type: `tool`, `session`, `agent`, `response`, `prompt`
+
+### Optional Arguments
+
+- `--message <text>` - Human-readable message
+- `--hook <hook>` - Hook name: `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `SessionEnd`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`
+- `--session-id <id>` - Claude Code session identifier
+- `--tool-name <name>` - Tool name (Bash, Read, Edit, Task, etc.)
+- `--tool-use-id <id>` - Correlates PreToolUse/PostToolUse pairs
+- `--status <status>` - Event outcome: `success`, `failure`, `pending`
+- `--data <json>` - JSON data string
+- `--stdin` - Read data object from stdin (JSON)
+- `--host <url>` - Argus host (default: `http://127.0.0.1:8765`)
+- `--api-key <key>` - Override API key from config
+- `-h, --help` - Show help
+
+### Environment Variables
+
+- `ARGUS_API_KEY` - Override config file API key
+- `ARGUS_HOST` - Override default host
+
+## Output Format
+
+```json
+{
+  "captured": true,
+  "event_id": 123
+}
+```
+
+## Configuration
+
+argus-send reads the API key from `~/.config/argus/config.toml` automatically:
+
+```toml
+[server]
+api_keys = ["your-api-key-here"]
+```
+
+No additional config needed. If the file doesn't exist, install Argus:
+
+```bash
+cd ~/development/projects/argus
+uv run argus config init
+```
+
+## Integration with Other Tools
+
+### gitignore-check
+
+```bash
+# Send compliance check results to Argus
+gitignore-check . | argus-send --source llcli-tools --type gitignore-check --stdin
+```
+
+### language-detect
+
+```bash
+# Track language detection events
+language-detect . | argus-send --source llcli-tools --type language-detect --stdin
+```
+
+### Momentum Hooks
+
+```typescript
+// In momentum pre-tool-use hook
+const result = Bun.spawnSync([
+  "argus-send",
+  "--source", "momentum",
+  "--type", "tool",
+  "--hook", "PreToolUse",
+  "--session-id", data.session_id,
+  "--tool-name", data.tool_name,
+  "--tool-use-id", data.tool_use_id,
+  "--message", `${data.tool_name}: ${summary}`
+]);
+```
+
+## Architecture
+
+- **Zero dependencies** - Uses Bun's native `fetch`
+- **TOML parsing** - Regex-based extraction (no TOML library needed)
+- **Synchronous POST** - Blocks until Argus stores event
+- **Stdin support** - Reads piped JSON for composability
+
+## Why Synchronous?
+
+Argus uses synchronous POST to guarantee event delivery before continuing. This prevents event loss on crashes and ensures observability gaps are filled.
+
+The tool blocks until Argus returns `{"status": "captured", "event_id": 123}`, confirming the event is durably stored in SQLite with WAL mode.
+
+## Error Handling
+
+**Exit codes:**
+- `0` - Event captured successfully
+- `1` - Argus server error (connection failed, rejected event)
+- `2` - Client error (missing args, invalid JSON, config not found)
+
+**Common errors:**
+
+```bash
+# API key not found
+❌ API key not found in config
+# Solution: Run `uv run argus config init` in argus project
+
+# Connection refused
+❌ Failed: Connection failed: error sending request
+# Solution: Start Argus server with `uv run argus serve`
+
+# Invalid JSON
+❌ Invalid JSON in --data
+# Solution: Check JSON syntax, ensure proper quotes
+```
+
+## Examples
+
+See [QUICKSTART.md](QUICKSTART.md) for comprehensive examples.
+
+## Related
+
+- [Argus](https://github.com/yourusername/argus) - Observability platform this tool sends to
+- [gitignore-check](../gitignore-check/) - Compliance checker that can pipe to argus-send
+- [language-detect](../language-detect/) - Language detector that can pipe to argus-send

package/cli.ts

@@ -0,0 +1,288 @@
+#!/usr/bin/env bun
+/**
+ * argus-send CLI
+ *
+ * Philosophy:
+ * - Synchronous delivery - Blocks until Argus confirms capture
+ * - Config-aware - Reads API key from ~/.config/argus/config.toml
+ * - Composable - Accepts data via --data flag or stdin pipe
+ *
+ * Usage:
+ *   argus-send --source <name> --type <event-type> [options]
+ *
+ * Exit codes:
+ *   0 - Event captured successfully
+ *   1 - Argus server error (connection failed, rejected event)
+ *   2 - Client error (missing args, invalid data, config not found)
+ */
+
+import {
+  sendEvent,
+  loadConfig,
+  type ArgusEvent,
+  type ArgusHook,
+  type ArgusStatus,
+} from "./index";
+
+// ============================================================================
+// Stdin Reading
+// ============================================================================
+
+/**
+ * Read JSON data from stdin
+ */
+async function readStdin(): Promise<unknown | null> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  if (chunks.length === 0) {
+    return null;
+  }
+
+  const input = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!input) return null;
+
+  try {
+    return JSON.parse(input);
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+/**
+ * Print usage and exit
+ */
+function printUsage(): void {
+  console.error(`
+argus-send - Send events to Argus observability platform
+
+Philosophy:
+  Synchronous delivery ensures event captured before continuing.
+  Config-aware tool reads API key from Argus config automatically.
+  Composable with other llcli tools via JSON piping.
+
+Usage: argus-send --source <name> --type <event-type> [options]
+
+Required:
+  --source <name>           Source name (e.g., "llcli-tools", "momentum")
+  --type <event-type>       Event type: tool, session, agent, response, prompt
+
+Optional:
+  --message <text>          Human-readable message
+  --hook <hook>             Hook name: PreToolUse, PostToolUse, Stop, SessionStart,
+                            SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit
+  --session-id <id>         Claude Code session identifier
+  --tool-name <name>        Tool name (Bash, Read, Edit, Task, etc.)
+  --tool-use-id <id>        Correlates PreToolUse/PostToolUse pairs
+  --status <status>         Event outcome: success, failure, pending
+  --data <json>             JSON data string
+  --stdin                   Read data from stdin (JSON)
+  --host <url>              Argus host (default: http://127.0.0.1:8765)
+  --api-key <key>           API key (default: from ~/.config/argus/config.toml)
+  -h, --help                Show this help
+
+Environment:
+  ARGUS_API_KEY             Override config file API key
+  ARGUS_HOST                Override default host
+
+Examples:
+  # Tool event
+  argus-send --source momentum --type tool \\
+    --hook PreToolUse \\
+    --session-id "f10e9765-1999-456f-81c3-eb4c531ecee2" \\
+    --tool-name Bash \\
+    --tool-use-id "toolu_01ABC" \\
+    --message "Bash: git status"
+
+  # Session event
+  argus-send --source momentum --type session \\
+    --hook SessionStart \\
+    --session-id "f10e9765-1999-456f-81c3-eb4c531ecee2" \\
+    --message "Session started: argus (active)"
+
+  # Pipe data from another tool
+  gitignore-check . | argus-send --source llcli-tools --type tool --stdin
+`);
+}
+
+interface ParsedArgs {
+  source: string;
+  eventType: string;
+  message?: string;
+  hook?: ArgusHook;
+  sessionId?: string;
+  toolName?: string;
+  toolUseId?: string;
+  status?: ArgusStatus;
+  dataStr?: string;
+  useStdin: boolean;
+  host: string;
+  apiKey: string | null;
+}
+
+/**
+ * Parse command-line arguments
+ */
+function parseArgs(
+  argv: string[],
+  config: ReturnType<typeof loadConfig>,
+): ParsedArgs | null {
+  const args = argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    return null;
+  }
+
+  // Check for deprecated --level flag
+  if (args.includes("--level")) {
+    console.error(
+      "❌ --level flag is deprecated and rejected by Argus API. Remove it from your command.",
+    );
+    process.exit(2);
+  }
+
+  let source: string | null = null;
+  let eventType: string | null = null;
+  let message: string | undefined;
+  let hook: ArgusHook | undefined;
+  let sessionId: string | undefined;
+  let toolName: string | undefined;
+  let toolUseId: string | undefined;
+  let status: ArgusStatus | undefined;
+  let dataStr: string | undefined;
+  let useStdin = false;
+  let host = process.env.ARGUS_HOST || config.host;
+  let apiKey: string | null = process.env.ARGUS_API_KEY || config.apiKey;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "--source" && i + 1 < args.length) {
+      source = args[++i];
+    } else if (arg === "--type" && i + 1 < args.length) {
+      eventType = args[++i];
+    } else if (arg === "--message" && i + 1 < args.length) {
+      message = args[++i];
+    } else if (arg === "--hook" && i + 1 < args.length) {
+      hook = args[++i] as ArgusHook;
+    } else if (arg === "--session-id" && i + 1 < args.length) {
+      sessionId = args[++i];
+    } else if (arg === "--tool-name" && i + 1 < args.length) {
+      toolName = args[++i];
+    } else if (arg === "--tool-use-id" && i + 1 < args.length) {
+      toolUseId = args[++i];
+    } else if (arg === "--status" && i + 1 < args.length) {
+      status = args[++i] as ArgusStatus;
+    } else if (arg === "--data" && i + 1 < args.length) {
+      dataStr = args[++i];
+    } else if (arg === "--stdin") {
+      useStdin = true;
+    } else if (arg === "--host" && i + 1 < args.length) {
+      host = args[++i];
+    } else if (arg === "--api-key" && i + 1 < args.length) {
+      apiKey = args[++i];
+    }
+  }
+
+  if (!source || !eventType) {
+    return null;
+  }
+
+  return {
+    source,
+    eventType,
+    message,
+    hook,
+    sessionId,
+    toolName,
+    toolUseId,
+    status,
+    dataStr,
+    useStdin,
+    host,
+    apiKey,
+  };
+}
+
+/**
+ * Main entry point
+ */
+async function main(): Promise<void> {
+  const config = loadConfig();
+  const parsed = parseArgs(process.argv, config);
+
+  if (!parsed) {
+    printUsage();
+    process.exit(parsed === null && process.argv.length > 2 ? 2 : 0);
+  }
+
+  // Validate API key
+  if (!parsed.apiKey) {
+    console.log(
+      JSON.stringify({
+        captured: false,
+        error: "API key not found (check ~/.config/argus/config.toml)",
+      }),
+    );
+    console.error("❌ API key not found in config");
+    process.exit(2);
+  }
+
+  // Build event
+  const event: ArgusEvent = {
+    source: parsed.source,
+    event_type: parsed.eventType,
+  };
+
+  if (parsed.message) event.message = parsed.message;
+  if (parsed.hook) event.hook = parsed.hook;
+  if (parsed.sessionId) event.session_id = parsed.sessionId;
+  if (parsed.toolName) event.tool_name = parsed.toolName;
+  if (parsed.toolUseId) event.tool_use_id = parsed.toolUseId;
+  if (parsed.status) event.status = parsed.status;
+
+  // Parse data from --data flag or stdin
+  if (parsed.useStdin) {
+    const stdinData = await readStdin();
+    if (stdinData) {
+      event.data = stdinData;
+    }
+  } else if (parsed.dataStr) {
+    try {
+      event.data = JSON.parse(parsed.dataStr);
+    } catch {
+      console.log(
+        JSON.stringify({
+          captured: false,
+          error: "Invalid JSON in --data argument",
+        }),
+      );
+      console.error("❌ Invalid JSON in --data");
+      process.exit(2);
+    }
+  }
+
+  // Send event
+  const result = await sendEvent(event, parsed.apiKey, parsed.host);
+
+  // Output JSON (stdout)
+  console.log(JSON.stringify(result));
+
+  // Diagnostic to stderr
+  if (result.captured) {
+    console.error(`✅ Event captured (ID: ${result.event_id})`);
+    process.exit(0);
+  } else {
+    console.error(`❌ Failed: ${result.error}`);
+    process.exit(1);
+  }
+}
+
+main();

package/index.ts

@@ -0,0 +1,187 @@
+/**
+ * argus-send - Library exports
+ *
+ * Send events to Argus observability platform.
+ * Pure functions, no process.exit, no stderr output.
+ *
+ * Usage:
+ *   import { sendEvent, loadConfig } from "argus-send";
+ *   const config = loadConfig();
+ *   const result = await sendEvent(event, config.apiKey!, config.host);
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ArgusEventType =
+  | "tool"
+  | "session"
+  | "agent"
+  | "response"
+  | "prompt";
+
+export type ArgusHook =
+  | "PreToolUse"
+  | "PostToolUse"
+  | "Stop"
+  | "SessionStart"
+  | "SessionEnd"
+  | "SubagentStart"
+  | "SubagentStop"
+  | "UserPromptSubmit";
+
+export type ArgusStatus = "success" | "failure" | "pending";
+
+export interface ArgusEvent {
+  source: string;
+  event_type: string;
+  timestamp?: string;
+  message?: string;
+  data?: unknown;
+  // Agent observability fields (send at top level, not in data)
+  session_id?: string;
+  hook?: ArgusHook;
+  tool_name?: string;
+  tool_use_id?: string;
+  status?: ArgusStatus;
+  agent_id?: string;
+}
+
+export interface SendResult {
+  captured: boolean;
+  event_id?: number;
+  error?: string;
+}
+
+export interface ArgusConfig {
+  host: string;
+  apiKey: string | null;
+}
+
+// ============================================================================
+// Config Loading
+// ============================================================================
+
+/**
+ * Load Argus configuration from config file
+ * Config: ~/.config/argus/config.toml
+ *
+ * @returns ArgusConfig with host URL and API key
+ */
+export function loadConfig(): ArgusConfig {
+  const configPath = join(process.env.HOME!, ".config", "argus", "config.toml");
+  const defaultHost = "http://127.0.0.1:8765";
+
+  if (!existsSync(configPath)) {
+    return { host: defaultHost, apiKey: null };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+
+    // Parse server.host (default: 127.0.0.1)
+    const hostMatch = content.match(/^\s*host\s*=\s*"([^"]+)"/m);
+    const host = hostMatch ? hostMatch[1] : "127.0.0.1";
+
+    // Parse server.port (default: 8765)
+    const portMatch = content.match(/^\s*port\s*=\s*(\d+)/m);
+    const port = portMatch ? portMatch[1] : "8765";
+
+    // Parse api_keys array, extract first key
+    const keysMatch = content.match(/api_keys\s*=\s*\[([^\]]+)\]/);
+    let apiKey: string | null = null;
+    if (keysMatch) {
+      const firstKey = keysMatch[1].match(/"([^"]+)"/);
+      apiKey = firstKey ? firstKey[1] : null;
+    }
+
+    return {
+      host: `http://${host}:${port}`,
+      apiKey,
+    };
+  } catch {
+    return { host: defaultHost, apiKey: null };
+  }
+}
+
+// ============================================================================
+// Main API
+// ============================================================================
+
+/**
+ * Send event to Argus
+ *
+ * @param event - The event to send
+ * @param apiKey - Argus API key
+ * @param host - Argus host URL (default: http://127.0.0.1:8765)
+ * @returns SendResult with captured status and event_id or error
+ */
+export async function sendEvent(
+  event: ArgusEvent,
+  apiKey: string,
+  host: string = "http://127.0.0.1:8765",
+): Promise<SendResult> {
+  try {
+    // Add timestamp if missing
+    const eventWithTimestamp = {
+      ...event,
+      timestamp: event.timestamp || new Date().toISOString(),
+    };
+
+    const response = await fetch(`${host}/events`, {
+      method: "POST",
+      headers: {
+        "X-API-Key": apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(eventWithTimestamp),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      return {
+        captured: false,
+        error: `HTTP ${response.status}: ${text}`,
+      };
+    }
+
+    const result = await response.json();
+    return {
+      captured: true,
+      event_id: result.event_id,
+    };
+  } catch (error) {
+    return {
+      captured: false,
+      error: `Connection failed: ${String(error)}`,
+    };
+  }
+}
+
+/**
+ * Send event using config from loadConfig()
+ * Convenience function that handles config loading
+ *
+ * @param event - The event to send
+ * @returns SendResult with captured status and event_id or error
+ */
+export async function send(event: ArgusEvent): Promise<SendResult> {
+  const config = loadConfig();
+
+  // Check environment overrides
+  const apiKey = process.env.ARGUS_API_KEY || config.apiKey;
+  const host = process.env.ARGUS_HOST || config.host;
+
+  if (!apiKey) {
+    return {
+      captured: false,
+      error: "API key not found (check ~/.config/argus/config.toml)",
+    };
+  }
+
+  return sendEvent(event, apiKey, host);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@voidwire/argus-send",
+  "version": "2.0.0",
+  "description": "Send events to Argus observability platform",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./cli": "./cli.ts"
+  },
+  "bin": {
+    "argus-send": "./cli.ts"
+  },
+  "files": [
+    "index.ts",
+    "cli.ts",
+    "lib/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run cli.ts"
+  },
+  "keywords": [
+    "argus",
+    "observability",
+    "events",
+    "llcli"
+  ],
+  "author": "nickpending <nickpending@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickpending/llmcli-tools.git",
+    "directory": "packages/argus-send"
+  },
+  "homepage": "https://github.com/nickpending/llmcli-tools/tree/main/packages/argus-send#readme",
+  "bugs": {
+    "url": "https://github.com/nickpending/llmcli-tools/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}