@observeone/cli 1.1.0 → 1.2.1

package/README.md

@@ -19,6 +19,7 @@ npm install -g @observeone/cli
 
 2. **Initialize Workspace**
    ```bash
+   # Creates local .obs.config.json
    obs init
    ```
 
@@ -27,7 +28,7 @@ npm install -g @observeone/cli
    obs export
    ```
 
-3. **Manage a monitor**
+4. **Manage a monitor**
    ```bash
    obs monitor create --name "My Website" --url "https://example.com" --interval "*/5 * * * *"
    obs monitor list
@@ -35,6 +36,18 @@ npm install -g @observeone/cli
 
 ---
 
+## Configuration Priority
+
+The CLI resolves configuration settings in the following order (highest to lowest priority):
+
+1.  **CLI Flags**: `--api-key`, `--api-url` passed directly to a command.
+2.  **Environment Variables**: `OBS_API_KEY`, `OBS_API_URL`.
+3.  **Local Config File**: `.obs.config.json` in the current working directory (created via `obs init`).
+4.  **Global Store**: Global OS configuration (saved after `obs login`).
+5.  **Defaults**: Internal default values.
+
+---
+
 ## Config-as-Code (Declarative Workflow)
 
 ObserveOne supports an Infrastructure-as-Code (IaC) workflow using JSON. You can define all your monitors, API checks, and heartbeats in a single `obs.json` file and sync them to your account.
@@ -65,6 +78,7 @@ obs apply -f my-stack.json
   "monitors": [
     {
       "name": "Production Website",
+      "description": "Main landing page monitor",
       "url": "https://example.com",
       "interval": "*/5 * * * *",
       "alert_on_failure": true
@@ -80,7 +94,8 @@ obs apply -f my-stack.json
   "heartbeats": [
     {
       "name": "Database Backup Job",
-      "period": 86400
+      "period": 86400,
+      "grace_period": 3600
     }
   ]
 }
@@ -93,7 +108,6 @@ obs apply -f my-stack.json
 You can manually create, read, update, delete, and toggle individual resources directly from the terminal.
 
 ### URL Monitors
-Manage basic HTTP ping monitors.
 ```bash
 obs monitor create --name "Frontend" --url "https://example.com" --interval "*/5 * * * *"
 obs monitor list
@@ -104,7 +118,6 @@ obs monitor delete <id> -y
 ```
 
 ### API Checks
-Manage complex API health checks.
 ```bash
 obs check create --name "Auth API" --url "https://api.example.com/auth" --method "POST"
 obs check list
@@ -114,51 +127,39 @@ obs check delete <id> -y
 ```
 
 ### Heartbeats (Cron Monitoring)
-Manage heartbeat checks (for monitoring background jobs or cron tasks).
 ```bash
-obs heartbeat create --name "Daily Backup" --period 86400
+obs heartbeat create --name "Daily Backup" --period 86400 --grace 3600
 obs heartbeat list
 obs heartbeat update <id> --period 43200
 obs heartbeat toggle <id>
 obs heartbeat delete <id> -y
 ```
 
-### AI Browser Checks
+---
+
+## AI Browser Checks
+
 Manage and execute intelligent Playwright-driven browser tests using natural language prompts.
-```bash
-obs ai-check create --name "Login Flow" --url "https://app.com" --prompt "Login with test@example.com"
-obs ai-check list
-obs ai-check get <id>
-obs ai-check delete <id> -y
-```
 
-#### Running AI Checks
-You can execute pre-configured checks or run them "ad-hoc" on the fly.
 ```bash
-# Run an existing test by name or ID
-obs ai-check run "Login Flow"
-obs ai-check run 123
+# Run an existing test and output JUnit report for CI
+obs ai-check run "Login Flow" --reporter junit
 
-# Run multiple tests sequentially
-obs ai-check run test1 test2 test3
+# Run multiple tests and output strict JSON for AI Agents
+obs ai-check run test1 test2 --reporter json
 
-# Run an ad-hoc test without saving it to the database
-obs ai-check run --adhoc --url https://example.com --prompt "Verify the hero section exists"
+# Run an ad-hoc test without saving it
+obs ai-check run --adhoc --url https://example.com --prompt "Verify login section exists"
 ```
 
 ---
 
 ## AI Agent Integration (Headless Mode)
 
-The `obs` CLI is explicitly designed to be used by AI coding agents (like Cursor, GitHub Copilot, Claude Code, or custom bots). 
+The `obs` CLI is explicitly designed to be used by AI coding agents.
 
 ### The `--json` Flag
-Append `--json` to **any** command. The CLI will automatically suppress all human-readable output (chalk colors, loading spinners, raw logs) and return a strict, machine-readable `JsonEnvelope`.
-
-```bash
-obs monitor list --json
-obs apply -f my-stack.json --json
-```
+Append `--json` to **any** command. The CLI will automatically suppress all human-readable output and return a strict, machine-readable `JsonEnvelope`.
 
 **Guaranteed Agent Response Schema:**
 ```json
@@ -170,42 +171,25 @@ obs apply -f my-stack.json --json
   }
 }
 ```
-*(If an error occurs, `status` will be `"ERROR"` and the envelope will contain a strict `error` object, preventing the agent's JSON parser from crashing).*
-
-### Headless Authentication & Account Setup
-Agents can create accounts and authenticate securely using environment variables without interactive browser prompts.
 
-#### Account Signup
-```bash
-# Create a secure account for automated bots (Rate-limited)
-obs signup
-```
-
-#### Headless Login
+### Headless Login
 Agents can authenticate securely using existing credentials:
 ```bash
 export OBS_EMAIL="agent@company.com"
 export OBS_PASSWORD="secure-password"
-
-# Automatically provisions and saves an API key to local config
 obs login --headless
 ```
 
-Alternatively, inject an existing API key directly into the environment:
-```bash
-export OBS_API_KEY="your_api_key_here"
-```
-
 ---
 
-## Global Configuration
+## Update Notifications
 
-Available for all commands:
-```bash
-obs <command> [options]
-```
+The CLI includes a non-blocking background update service that checks for newer versions on npm. If an update is available, a notification will be displayed at the start of your command output. This check is automatically disabled in `--json` mode.
+
+---
+
+## Global Options
 
-**Options:**
 - `-v, --verbose` - Enable verbose output and stack traces
 - `--json` - Output in strict JSON format
 - `--api-url <url>` - Override API URL
@@ -213,14 +197,6 @@ obs <command> [options]
 - `--version` - Show version number
 - `--help` - Show help
 
-### Environment Variables
-```bash
-export OBS_API_URL=https://api.observeone.com
-export OBS_API_KEY=your-api-key
-export OBS_VERBOSE=true
-export OBS_JSON_OUTPUT=true
-```
-
 ## License
 MIT
 

package/dist/README.md

@@ -19,6 +19,7 @@ npm install -g @observeone/cli
 
 2. **Initialize Workspace**
    ```bash
+   # Creates local .obs.config.json
    obs init
    ```
 
@@ -27,7 +28,7 @@ npm install -g @observeone/cli
    obs export
    ```
 
-3. **Manage a monitor**
+4. **Manage a monitor**
    ```bash
    obs monitor create --name "My Website" --url "https://example.com" --interval "*/5 * * * *"
    obs monitor list
@@ -35,6 +36,18 @@ npm install -g @observeone/cli
 
 ---
 
+## Configuration Priority
+
+The CLI resolves configuration settings in the following order (highest to lowest priority):
+
+1.  **CLI Flags**: `--api-key`, `--api-url` passed directly to a command.
+2.  **Environment Variables**: `OBS_API_KEY`, `OBS_API_URL`.
+3.  **Local Config File**: `.obs.config.json` in the current working directory (created via `obs init`).
+4.  **Global Store**: Global OS configuration (saved after `obs login`).
+5.  **Defaults**: Internal default values.
+
+---
+
 ## Config-as-Code (Declarative Workflow)
 
 ObserveOne supports an Infrastructure-as-Code (IaC) workflow using JSON. You can define all your monitors, API checks, and heartbeats in a single `obs.json` file and sync them to your account.
@@ -65,6 +78,7 @@ obs apply -f my-stack.json
   "monitors": [
     {
       "name": "Production Website",
+      "description": "Main landing page monitor",
       "url": "https://example.com",
       "interval": "*/5 * * * *",
       "alert_on_failure": true
@@ -80,7 +94,8 @@ obs apply -f my-stack.json
   "heartbeats": [
     {
       "name": "Database Backup Job",
-      "period": 86400
+      "period": 86400,
+      "grace_period": 3600
     }
   ]
 }
@@ -93,7 +108,6 @@ obs apply -f my-stack.json
 You can manually create, read, update, delete, and toggle individual resources directly from the terminal.
 
 ### URL Monitors
-Manage basic HTTP ping monitors.
 ```bash
 obs monitor create --name "Frontend" --url "https://example.com" --interval "*/5 * * * *"
 obs monitor list
@@ -104,7 +118,6 @@ obs monitor delete <id> -y
 ```
 
 ### API Checks
-Manage complex API health checks.
 ```bash
 obs check create --name "Auth API" --url "https://api.example.com/auth" --method "POST"
 obs check list
@@ -114,51 +127,39 @@ obs check delete <id> -y
 ```
 
 ### Heartbeats (Cron Monitoring)
-Manage heartbeat checks (for monitoring background jobs or cron tasks).
 ```bash
-obs heartbeat create --name "Daily Backup" --period 86400
+obs heartbeat create --name "Daily Backup" --period 86400 --grace 3600
 obs heartbeat list
 obs heartbeat update <id> --period 43200
 obs heartbeat toggle <id>
 obs heartbeat delete <id> -y
 ```
 
-### AI Browser Checks
+---
+
+## AI Browser Checks
+
 Manage and execute intelligent Playwright-driven browser tests using natural language prompts.
-```bash
-obs ai-check create --name "Login Flow" --url "https://app.com" --prompt "Login with test@example.com"
-obs ai-check list
-obs ai-check get <id>
-obs ai-check delete <id> -y
-```
 
-#### Running AI Checks
-You can execute pre-configured checks or run them "ad-hoc" on the fly.
 ```bash
-# Run an existing test by name or ID
-obs ai-check run "Login Flow"
-obs ai-check run 123
+# Run an existing test and output JUnit report for CI
+obs ai-check run "Login Flow" --reporter junit
 
-# Run multiple tests sequentially
-obs ai-check run test1 test2 test3
+# Run multiple tests and output strict JSON for AI Agents
+obs ai-check run test1 test2 --reporter json
 
-# Run an ad-hoc test without saving it to the database
-obs ai-check run --adhoc --url https://example.com --prompt "Verify the hero section exists"
+# Run an ad-hoc test without saving it
+obs ai-check run --adhoc --url https://example.com --prompt "Verify login section exists"
 ```
 
 ---
 
 ## AI Agent Integration (Headless Mode)
 
-The `obs` CLI is explicitly designed to be used by AI coding agents (like Cursor, GitHub Copilot, Claude Code, or custom bots). 
+The `obs` CLI is explicitly designed to be used by AI coding agents.
 
 ### The `--json` Flag
-Append `--json` to **any** command. The CLI will automatically suppress all human-readable output (chalk colors, loading spinners, raw logs) and return a strict, machine-readable `JsonEnvelope`.
-
-```bash
-obs monitor list --json
-obs apply -f my-stack.json --json
-```
+Append `--json` to **any** command. The CLI will automatically suppress all human-readable output and return a strict, machine-readable `JsonEnvelope`.
 
 **Guaranteed Agent Response Schema:**
 ```json
@@ -170,42 +171,25 @@ obs apply -f my-stack.json --json
   }
 }
 ```
-*(If an error occurs, `status` will be `"ERROR"` and the envelope will contain a strict `error` object, preventing the agent's JSON parser from crashing).*
-
-### Headless Authentication & Account Setup
-Agents can create accounts and authenticate securely using environment variables without interactive browser prompts.
 
-#### Account Signup
-```bash
-# Create a secure account for automated bots (Rate-limited)
-obs signup
-```
-
-#### Headless Login
+### Headless Login
 Agents can authenticate securely using existing credentials:
 ```bash
 export OBS_EMAIL="agent@company.com"
 export OBS_PASSWORD="secure-password"
-
-# Automatically provisions and saves an API key to local config
 obs login --headless
 ```
 
-Alternatively, inject an existing API key directly into the environment:
-```bash
-export OBS_API_KEY="your_api_key_here"
-```
-
 ---
 
-## Global Configuration
+## Update Notifications
 
-Available for all commands:
-```bash
-obs <command> [options]
-```
+The CLI includes a non-blocking background update service that checks for newer versions on npm. If an update is available, a notification will be displayed at the start of your command output. This check is automatically disabled in `--json` mode.
+
+---
+
+## Global Options
 
-**Options:**
 - `-v, --verbose` - Enable verbose output and stack traces
 - `--json` - Output in strict JSON format
 - `--api-url <url>` - Override API URL
@@ -213,14 +197,6 @@ obs <command> [options]
 - `--version` - Show version number
 - `--help` - Show help
 
-### Environment Variables
-```bash
-export OBS_API_URL=https://api.observeone.com
-export OBS_API_KEY=your-api-key
-export OBS_VERBOSE=true
-export OBS_JSON_OUTPUT=true
-```
-
 ## License
 MIT
 

package/dist/commands/ai-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-check.d.ts","sourceRoot":"","sources":["../../src/commands/ai-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMnE;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,cAAc,EAC7B,SAAS,EAAE,UAAU,EACrB,aAAa,EAAE,cAAc,GAC5B,OAAO,CA+QT"}
+{"version":3,"file":"ai-check.d.ts","sourceRoot":"","sources":["../../src/commands/ai-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAqBnE;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,cAAc,EAC7B,SAAS,EAAE,UAAU,EACrB,aAAa,EAAE,cAAc,GAC5B,OAAO,CAyRT"}

package/dist/commands/ai-check.js

@@ -69,7 +69,9 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
         .option('-f, --format <format>', 'Output format (table, json)', 'table')
         .option('-j, --json', 'Output in JSON format')
         .action(async (options) => {
-        if (process.env.OBS_JSON_OUTPUT === 'true' || options.format === 'json' || options.json) {
+        if (process.env.OBS_JSON_OUTPUT === 'true' ||
+            options.format === 'json' ||
+            options.json === true) {
             outputService.enableJsonMode();
         }
         try {
@@ -80,7 +82,9 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
             }
             outputService.progress('Fetching AI checks...');
             const tests = await apiClient.getTests();
-            if (process.env.OBS_JSON_OUTPUT === 'true' || options.format === 'json' || options.json) {
+            if (process.env.OBS_JSON_OUTPUT === 'true' ||
+                options.format === 'json' ||
+                options.json === true) {
                 outputService.formatJsonOutput(tests);
             }
             else {
@@ -98,7 +102,7 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
         .description('Get details of an AI browser check')
         .option('-j, --json', 'Output in JSON format')
         .action(async (id, options) => {
-        if (process.env.OBS_JSON_OUTPUT === 'true' || options.json) {
+        if (process.env.OBS_JSON_OUTPUT === 'true' || options.json === true) {
             outputService.enableJsonMode();
         }
         try {
@@ -135,7 +139,7 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
         .option('-p, --prompt <prompt>', 'Test prompt')
         .option('-j, --json', 'Output in JSON format')
         .action(async (options) => {
-        if (process.env.OBS_JSON_OUTPUT === 'true' || options.json) {
+        if (process.env.OBS_JSON_OUTPUT === 'true' || options.json === true) {
             outputService.enableJsonMode();
         }
         try {
@@ -144,7 +148,9 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
                 outputService.error('Not authenticated. Please run "obs login" first.');
                 process.exit(1);
             }
-            let { name, url, prompt } = options;
+            let name = options.name;
+            let url = options.url;
+            let prompt = options.prompt;
             if (!name || !url || !prompt) {
                 const answers = await inquirer.prompt([
                     {
@@ -183,9 +189,9 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
             }
             outputService.progress('Creating AI browser check...');
             const newTest = await apiClient.createTest({
-                name,
-                url,
-                prompt,
+                name: name,
+                url: url,
+                prompt: prompt,
                 description: 'Created via CLI',
             });
             if (process.env.OBS_JSON_OUTPUT === 'true') {
@@ -207,7 +213,7 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
         .option('-y, --yes', 'Skip confirmation prompt')
         .option('-j, --json', 'Output in JSON format')
         .action(async (id, options) => {
-        if (process.env.OBS_JSON_OUTPUT === 'true' || options.json) {
+        if (process.env.OBS_JSON_OUTPUT === 'true' || options.json === true) {
             outputService.enableJsonMode();
         }
         try {
@@ -254,7 +260,7 @@ export function createAiCheckCommand(configService, apiClient, outputService) {
  */
 async function runAdhocTest(apiClient, outputService, configService, options, timeout, results, shouldWait, isJson) {
     const spinner = isJson
-        ? { start: () => { }, succeed: () => { }, fail: () => { } }
+        ? { start: () => { }, succeed: (_msg) => { }, fail: (_msg) => { } }
         : ora('Running ad-hoc test...').start();
     try {
         const result = await apiClient.executeAdhocTest({
@@ -278,9 +284,9 @@ async function runAdhocTest(apiClient, outputService, configService, options, ti
 /**
  * Run named tests
  */
-async function runNamedTests(apiClient, outputService, configService, testNames, options, timeout, results, shouldWait, isJson) {
+async function runNamedTests(apiClient, _outputService, configService, testNames, options, timeout, results, shouldWait, isJson) {
     const spinner = isJson
-        ? { start: () => { }, succeed: () => { }, fail: () => { } }
+        ? { start: () => { }, succeed: (_msg) => { }, fail: (_msg) => { } }
         : ora('Fetching test details...').start();
     try {
         const tests = await apiClient.getTests();
@@ -304,7 +310,7 @@ async function runNamedTests(apiClient, outputService, configService, testNames,
         // Execute each test
         for (const test of testsToRun) {
             const testSpinner = isJson
-                ? { start: () => { }, succeed: () => { }, fail: () => { } }
+                ? { start: () => { }, succeed: (_msg) => { }, fail: (_msg) => { } }
                 : ora(`Running test: ${test.name}`).start();
             try {
                 const result = await apiClient.executeTest(test.id);
@@ -355,7 +361,7 @@ async function streamTestProgress(configService, result, testName, options, time
         if (message.type === 'step_update' && message.step) {
             stepCounter++;
             const step = message.step;
-            if (!silent) {
+            if (!silent && renderer && logger) {
                 if (message.screenshot) {
                     renderer.addScreenshot();
                     logger.writeScreenshot(stepCounter);
@@ -365,14 +371,14 @@ async function streamTestProgress(configService, result, testName, options, time
             }
         }
         else if (message.type === 'screenshot') {
-            if (!silent) {
+            if (!silent && renderer && logger) {
                 renderer.addScreenshot();
                 logger.writeScreenshot(stepCounter);
             }
         }
         else if (message.type === 'complete' || message.type === 'task_completed') {
             const status = message.status === 'failed' ? 'failed' : 'success';
-            if (!silent) {
+            if (!silent && renderer && logger) {
                 renderer.complete(status, message.message);
                 logger.writeComplete(status, message.message);
             }
@@ -386,13 +392,13 @@ async function streamTestProgress(configService, result, testName, options, time
             };
             completed = true;
             sseClient.close();
-            if (!silent) {
+            if (!silent && logger) {
                 logger.close();
                 console.log(chalk.gray(`\nDetailed logs: ${logger.getPath()}`));
             }
         }
         else if (message.type === 'error') {
-            if (!silent) {
+            if (!silent && renderer && logger) {
                 renderer.error(message.message || 'Test failed');
                 logger.writeComplete('failed', message.message);
             }
@@ -403,23 +409,24 @@ async function streamTestProgress(configService, result, testName, options, time
             };
             completed = true;
             sseClient.close();
-            if (!silent) {
+            if (!silent && logger) {
                 logger.close();
             }
         }
     }, (error) => {
         if (!completed) {
-            if (!silent) {
-                renderer.error(`Connection error: ${error.message}`);
-                logger.writeComplete('failed', `Connection error: ${error.message}`);
+            const err = error;
+            if (!silent && renderer && logger) {
+                renderer.error(`Connection error: ${err.message}`);
+                logger.writeComplete('failed', `Connection error: ${err.message}`);
             }
             results[results.length - 1] = {
                 ...result,
                 status: 'FAILED',
-                message: `Connection error: ${error.message}`,
+                message: `Connection error: ${err.message}`,
             };
             sseClient.close();
-            if (!silent) {
+            if (!silent && logger) {
                 logger.close();
             }
             completed = true;
@@ -436,7 +443,7 @@ async function streamTestProgress(configService, result, testName, options, time
         setTimeout(() => {
             if (!completed) {
                 clearInterval(checkInterval);
-                if (!silent) {
+                if (!silent && renderer) {
                     renderer.error('Test execution timed out');
                 }
                 results[results.length - 1] = {
@@ -445,7 +452,7 @@ async function streamTestProgress(configService, result, testName, options, time
                     message: 'Test execution timed out',
                 };
                 sseClient.close();
-                if (!silent) {
+                if (!silent && logger) {
                     logger.close();
                 }
                 resolve();
@@ -507,11 +514,11 @@ function generateJUnitReport(results, outputService) {
         tests: results.length,
         failures: results.filter((r) => r.status === 'FAILED').length,
         errors: 0,
-        time: results.reduce((total, r) => total + (r.duration || 0), 0) / 1000,
+        time: (results.reduce((total, r) => total + (r.duration || 0), 0) / 1000).toString(),
         testCases: results.map((result, index) => ({
             name: `Test ${index + 1}`,
             classname: 'observeone.test',
-            time: (result.duration || 0) / 1000,
+            time: ((result.duration || 0) / 1000).toString(),
             status: result.status === 'SUCCESS' ? 'passed' : 'failed',
             failure: result.status === 'FAILED'
                 ? {