@lde/sparql-monitor 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,85 @@ Monitor SPARQL endpoints with periodic checks, storing observations in PostgreSQ
 npm install @lde/sparql-monitor
 ```
 
-## Usage
+## CLI Usage
+
+The easiest way to use the monitor is via the CLI with a configuration file.
+
+### Quick Start
+
+1. Create a configuration file (TypeScript, JavaScript, JSON, or YAML)
+2. Run the monitor
+
+```bash
+# Start continuous monitoring
+npx sparql-monitor start
+
+# Run a one-off check
+npx sparql-monitor check
+
+# Check a specific monitor
+npx sparql-monitor check dbpedia
+
+# Use a custom config path
+npx sparql-monitor start --config ./configs/production.config.ts
+```
+
+### TypeScript Config (`sparql-monitor.config.ts`)
+
+```typescript
+import { defineConfig } from '@lde/sparql-monitor';
+
+export default defineConfig({
+  databaseUrl: process.env.DATABASE_URL,
+  intervalSeconds: 300,
+  monitors: [
+    {
+      identifier: 'dbpedia',
+      endpointUrl: new URL('https://dbpedia.org/sparql'),
+      query: 'ASK { ?s ?p ?o }',
+    },
+    {
+      identifier: 'wikidata',
+      endpointUrl: new URL('https://query.wikidata.org/sparql'),
+      query: 'SELECT * WHERE { ?s ?p ?o } LIMIT 1',
+    },
+  ],
+});
+```
+
+### YAML Config (`sparql-monitor.config.yaml`)
+
+```yaml
+databaseUrl: ${DATABASE_URL}
+intervalSeconds: 300
+monitors:
+  - identifier: dbpedia
+    endpointUrl: https://dbpedia.org/sparql
+    query: ASK { ?s ?p ?o }
+  - identifier: wikidata
+    endpointUrl: https://query.wikidata.org/sparql
+    query: SELECT * WHERE { ?s ?p ?o } LIMIT 1
+```
+
+### Environment Variables
+
+Create a `.env` file for sensitive configuration:
+
+```
+DATABASE_URL=postgres://user:pass@localhost:5432/monitoring
+```
+
+The CLI automatically loads `.env` files.
+
+### Config Auto-Discovery
+
+The CLI searches for configuration in this order:
+
+1. `sparql-monitor.config.{ts,mts,js,mjs,json,yaml,yml}`
+2. `.sparql-monitorrc`
+3. `package.json` → `"sparql-monitor"` key
+
+## Programmatic Usage
 
 ```typescript
 import {

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { loadConfig } from 'c12';
+import { createRequire } from 'node:module';
+import { MonitorService } from './service.js';
+import { PostgresObservationStore } from './store.js';
+import { normalizeConfig } from './config.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+async function loadMonitorContext(configFile) {
+    const { config: rawConfig } = await loadConfig({
+        name: 'sparql-monitor',
+        configFile,
+        dotenv: true,
+    });
+    if (!rawConfig) {
+        console.error('Error: No configuration found.');
+        console.error('Create a sparql-monitor.config.ts file or specify --config.');
+        process.exit(1);
+    }
+    const config = normalizeConfig(rawConfig);
+    const databaseUrl = config.databaseUrl ?? process.env.DATABASE_URL;
+    if (!databaseUrl) {
+        console.error('Error: databaseUrl required (set in config or DATABASE_URL env).');
+        process.exit(1);
+    }
+    if (config.monitors.length === 0) {
+        console.error('Error: No monitors configured.');
+        process.exit(1);
+    }
+    const store = await PostgresObservationStore.create(databaseUrl);
+    const service = new MonitorService({
+        store,
+        monitors: config.monitors,
+        intervalSeconds: config.intervalSeconds,
+    });
+    return {
+        config: { ...config, databaseUrl },
+        store,
+        service,
+    };
+}
+const program = new Command();
+program
+    .name('sparql-monitor')
+    .description('Monitor SPARQL endpoints')
+    .version(version);
+program
+    .command('start')
+    .description('Start monitoring all configured endpoints')
+    .option('-c, --config <path>', 'Config file path')
+    .action(async (options) => {
+    const { config, store, service } = await loadMonitorContext(options.config);
+    await service.checkAll();
+    service.start();
+    console.log(`Monitoring ${config.monitors.length} endpoint(s)...`);
+    console.log(`Interval: ${config.intervalSeconds ?? 300} seconds`);
+    const shutdown = async () => {
+        console.log('\nShutting down...');
+        service.stop();
+        await store.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+});
+program
+    .command('check [identifier]')
+    .description('Run immediate check (all monitors or specific one)')
+    .option('-c, --config <path>', 'Config file path')
+    .action(async (identifier, options) => {
+    const { config, store, service } = await loadMonitorContext(options.config);
+    try {
+        if (identifier) {
+            const monitor = config.monitors.find((m) => m.identifier === identifier);
+            if (!monitor) {
+                console.error(`Error: Monitor '${identifier}' not found.`);
+                console.error('Available monitors:', config.monitors.map((m) => m.identifier).join(', '));
+                process.exit(1);
+            }
+            console.log(`Checking ${identifier}...`);
+            await service.checkNow(identifier);
+            console.log(`Check completed for ${identifier}.`);
+        }
+        else {
+            console.log(`Checking ${config.monitors.length} endpoint(s)...`);
+            await service.checkAll();
+            console.log('All checks completed.');
+        }
+    }
+    finally {
+        await store.close();
+    }
+});
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import type { MonitorConfig } from './types.js';
+/**
+ * Raw config as loaded from file (URL can be string or URL).
+ */
+export interface RawMonitorConfig {
+    /** Unique identifier for this monitor. */
+    identifier: string;
+    /** URL of the SPARQL endpoint to monitor (string or URL). */
+    endpointUrl: string | URL;
+    /** SPARQL query to execute. */
+    query: string;
+}
+/**
+ * Configuration for the SPARQL monitor.
+ */
+export interface SparqlMonitorConfig {
+    /** PostgreSQL connection string. */
+    databaseUrl?: string;
+    /** Polling interval in seconds (default: 300). */
+    intervalSeconds?: number;
+    /** Monitor definitions. */
+    monitors: RawMonitorConfig[];
+}
+/**
+ * Type helper for TypeScript config files.
+ *
+ * @example
+ * ```ts
+ * // sparql-monitor.config.ts
+ * import { defineConfig } from '@lde/sparql-monitor';
+ *
+ * export default defineConfig({
+ *   databaseUrl: process.env.DATABASE_URL,
+ *   intervalSeconds: 300,
+ *   monitors: [
+ *     {
+ *       identifier: 'dbpedia',
+ *       endpointUrl: new URL('https://dbpedia.org/sparql'),
+ *       query: 'ASK { ?s ?p ?o }',
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export declare function defineConfig(config: SparqlMonitorConfig): SparqlMonitorConfig;
+/**
+ * Normalize config (convert string URLs to URL objects).
+ */
+export declare function normalizeConfig(raw: SparqlMonitorConfig): {
+    databaseUrl?: string;
+    intervalSeconds?: number;
+    monitors: MonitorConfig[];
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC;IAC1B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAE7E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAWA"}

package/dist/config.js

@@ -0,0 +1,38 @@
+/**
+ * Type helper for TypeScript config files.
+ *
+ * @example
+ * ```ts
+ * // sparql-monitor.config.ts
+ * import { defineConfig } from '@lde/sparql-monitor';
+ *
+ * export default defineConfig({
+ *   databaseUrl: process.env.DATABASE_URL,
+ *   intervalSeconds: 300,
+ *   monitors: [
+ *     {
+ *       identifier: 'dbpedia',
+ *       endpointUrl: new URL('https://dbpedia.org/sparql'),
+ *       query: 'ASK { ?s ?p ?o }',
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Normalize config (convert string URLs to URL objects).
+ */
+export function normalizeConfig(raw) {
+    return {
+        ...raw,
+        monitors: raw.monitors.map((m) => ({
+            ...m,
+            endpointUrl: typeof m.endpointUrl === 'string'
+                ? new URL(m.endpointUrl)
+                : m.endpointUrl,
+        })),
+    };
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { MonitorConfig, Observation, ObservationStore } from './types.js';
 export { PostgresObservationStore } from './store.js';
 export { MonitorService, type MonitorServiceOptions } from './service.js';
+export { defineConfig, type SparqlMonitorConfig } from './config.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { PostgresObservationStore } from './store.js';
 export { MonitorService } from './service.js';
+export { defineConfig } from './config.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/sparql-monitor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Monitor SPARQL endpoints with periodic checks",
   "repository": {
     "url": "https://github.com/ldengine/lde"
@@ -18,11 +18,16 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "sparql-monitor": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
+    "c12": "^3.0.2",
+    "commander": "^13.1.0",
     "cron": "^4.1.0",
     "drizzle-kit": "^0.30.4",
     "drizzle-orm": "^0.38.4",