@eltonssouza/development-utility-kit 1.0.0

package/bin/lib/version-check.js

@@ -0,0 +1,398 @@
+'use strict';
+
+/**
+ * version-check.js — Fetch latest versions for ecosystems and compare semver.
+ *
+ * Uses Node's native https module (no fetch — Node 18 compat). Caches at
+ * ~/.duk/cache/versions.json (TTL 24h). Falls back to scripts/latest-versions.json
+ * when network fails. All network operations are best-effort and silent on error.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const NETWORK_TIMEOUT_MS = 5000;
+
+/**
+ * Resolve the cache file path.
+ * @returns {string}
+ */
+function getCachePath() {
+  return path.join(os.homedir(), '.duk', 'cache', 'versions.json');
+}
+
+/**
+ * Resolve the offline fallback JSON path (shipped with the harness).
+ * @returns {string}
+ */
+function getFallbackPath() {
+  return path.resolve(__dirname, '..', '..', 'scripts', 'latest-versions.json');
+}
+
+/**
+ * Read JSON file safely; returns null on any error.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write JSON file, creating parent dirs as needed. Best-effort; swallows errors.
+ * @param {string} filePath
+ * @param {object} data
+ */
+function writeJsonSafe(filePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * HTTPS GET with timeout. Resolves to response body string or rejects.
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      url,
+      {
+        headers: {
+          'User-Agent': 'duk-cli/0.1 (https://github.com/eltonssouza/development-utility-kit)',
+          Accept: 'application/json',
+        },
+      },
+      (res) => {
+        if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          // Single redirect hop
+          httpsGet(res.headers.location).then(resolve, reject);
+          return;
+        }
+        if (!res.statusCode || res.statusCode >= 400) {
+          res.resume();
+          reject(new Error(`HTTP ${res.statusCode}`));
+          return;
+        }
+        let data = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => resolve(data));
+        res.on('error', reject);
+      }
+    );
+
+    req.setTimeout(NETWORK_TIMEOUT_MS, () => {
+      req.destroy(new Error('timeout'));
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Query Maven Central for the latest version of a g:a coordinate.
+ * @param {string} groupId
+ * @param {string} artifactId
+ * @returns {Promise<string|null>}
+ */
+async function mavenCentralLatest(groupId, artifactId) {
+  const url =
+    `https://search.maven.org/solrsearch/select?q=g:${encodeURIComponent(groupId)}+AND+a:${encodeURIComponent(artifactId)}` +
+    `&rows=1&wt=json`;
+  try {
+    const body = await httpsGet(url);
+    const json = JSON.parse(body);
+    const doc = json && json.response && Array.isArray(json.response.docs) && json.response.docs[0];
+    return doc && doc.latestVersion ? String(doc.latestVersion) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query npm registry for dist-tags.latest of a package.
+ * @param {string} pkgName
+ * @returns {Promise<string|null>}
+ */
+async function npmRegistryLatest(pkgName) {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(pkgName).replace('%40', '@')}`;
+  try {
+    const body = await httpsGet(url);
+    const json = JSON.parse(body);
+    return json && json['dist-tags'] && json['dist-tags'].latest
+      ? String(json['dist-tags'].latest)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query GitHub releases for tag_name of latest release.
+ * @param {string} owner
+ * @param {string} repo
+ * @returns {Promise<string|null>}
+ */
+async function githubReleasesLatest(owner, repo) {
+  const url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/releases/latest`;
+  try {
+    const body = await httpsGet(url);
+    const json = JSON.parse(body);
+    const tag = json && json.tag_name ? String(json.tag_name) : null;
+    if (!tag) return null;
+    // strip leading 'v'
+    return tag.replace(/^v/i, '');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Determine ecosystem + identifier per framework, then call the right API.
+ * @param {string} framework
+ * @returns {Promise<string|null>}
+ */
+async function fetchFrameworkLatest(framework) {
+  switch (framework) {
+    case 'spring-boot':
+      return mavenCentralLatest('org.springframework.boot', 'spring-boot');
+    case 'angular':
+      return npmRegistryLatest('@angular/core');
+    case 'react':
+      return npmRegistryLatest('react');
+    case 'react-native':
+      return npmRegistryLatest('react-native');
+    case 'next':
+      return npmRegistryLatest('next');
+    case 'nuxt':
+      return npmRegistryLatest('nuxt');
+    case 'vue':
+      return npmRegistryLatest('vue');
+    case 'nest':
+      return npmRegistryLatest('@nestjs/core');
+    case 'express':
+      return npmRegistryLatest('express');
+    case 'fastify':
+      return npmRegistryLatest('fastify');
+    case 'django':
+      return githubReleasesLatest('django', 'django');
+    case 'fastapi':
+      return githubReleasesLatest('fastapi', 'fastapi');
+    case 'flask':
+      return githubReleasesLatest('pallets', 'flask');
+    case 'gin':
+      return githubReleasesLatest('gin-gonic', 'gin');
+    case 'echo':
+      return githubReleasesLatest('labstack', 'echo');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Determine the latest version of a language runtime (uses fallback JSON in
+ * practice — language runtime cadence does not move fast enough to warrant
+ * an API call per install).
+ * @param {string} language
+ * @param {object} fallback
+ * @returns {string|null}
+ */
+function languageLatestFromFallback(language, fallback) {
+  if (!fallback) return null;
+  switch (language) {
+    case 'java':
+      return (fallback.java && (fallback.java.latest_lts || fallback.java.latest)) || null;
+    case 'node':
+    case 'typescript':
+    case 'javascript':
+      return (fallback.node && (fallback.node.latest_lts || fallback.node.latest)) || null;
+    case 'python':
+      return (fallback.python && (fallback.python.latest_stable || fallback.python.latest)) || null;
+    case 'go':
+      return (fallback.go && fallback.go.latest) || null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Cache the result of fetchFrameworkLatest using the local versions.json cache.
+ * @param {string} framework
+ * @returns {Promise<string|null>}
+ */
+async function getFrameworkLatestCached(framework) {
+  const cachePath = getCachePath();
+  const cache = readJsonSafe(cachePath) || { _ts: 0, frameworks: {} };
+
+  const now = Date.now();
+  const fresh = cache._ts && now - cache._ts < CACHE_TTL_MS;
+  if (fresh && cache.frameworks && cache.frameworks[framework]) {
+    return cache.frameworks[framework];
+  }
+
+  const latest = await fetchFrameworkLatest(framework);
+  if (latest) {
+    cache.frameworks = cache.frameworks || {};
+    cache.frameworks[framework] = latest;
+    cache._ts = now;
+    writeJsonSafe(cachePath, cache);
+    return latest;
+  }
+
+  // No network — fall back to static JSON shipped with the harness
+  const fallback = readJsonSafe(getFallbackPath());
+  if (fallback && fallback[framework] && fallback[framework].latest) {
+    return fallback[framework].latest;
+  }
+
+  // Stale cache > nothing
+  if (cache.frameworks && cache.frameworks[framework]) {
+    return cache.frameworks[framework];
+  }
+  return null;
+}
+
+/**
+ * Get latest versions for a stack descriptor.
+ * @param {{language: string, framework: string}} stack
+ * @returns {Promise<{language_latest: string|null, framework_latest: string|null}>}
+ */
+async function getLatestVersions(stack) {
+  if (!stack || typeof stack !== 'object') {
+    return { language_latest: null, framework_latest: null };
+  }
+
+  const fallback = readJsonSafe(getFallbackPath());
+  const language_latest = languageLatestFromFallback(stack.language, fallback);
+  const framework_latest = await getFrameworkLatestCached(stack.framework);
+  return { language_latest, framework_latest };
+}
+
+/**
+ * Force-refresh the entire cache for all known frameworks.
+ * @returns {Promise<object>} the new cache contents
+ */
+async function refreshLatestVersions() {
+  const frameworks = [
+    'spring-boot',
+    'angular',
+    'react',
+    'react-native',
+    'next',
+    'nuxt',
+    'vue',
+    'nest',
+    'express',
+    'fastify',
+    'django',
+    'fastapi',
+    'flask',
+    'gin',
+    'echo',
+  ];
+  const cache = { _ts: Date.now(), frameworks: {} };
+  for (const f of frameworks) {
+    const v = await fetchFrameworkLatest(f);
+    if (v) cache.frameworks[f] = v;
+  }
+  writeJsonSafe(getCachePath(), cache);
+  return cache;
+}
+
+// ─── semver compare ──────────────────────────────────────────────────────────
+
+/**
+ * Parse a semver-ish string into [major, minor, patch] integers.
+ * Pre-release and build metadata are dropped.
+ * @param {string} v
+ * @returns {[number, number, number]}
+ */
+function parseSemver(v) {
+  if (!v || typeof v !== 'string') return [0, 0, 0];
+  const m = v.match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return [0, 0, 0];
+  return [parseInt(m[1], 10) || 0, parseInt(m[2] || '0', 10), parseInt(m[3] || '0', 10)];
+}
+
+/**
+ * Compare two versions. Returns -1, 0, or 1.
+ * Accepts plain semver only.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function compareSemverPair(a, b) {
+  const [a1, a2, a3] = parseSemver(a);
+  const [b1, b2, b3] = parseSemver(b);
+  if (a1 !== b1) return a1 < b1 ? -1 : 1;
+  if (a2 !== b2) return a2 < b2 ? -1 : 1;
+  if (a3 !== b3) return a3 < b3 ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Compare two versions (or a version against a range expression).
+ *
+ * Plain compare (both args plain versions): returns -1, 0, 1.
+ *
+ * Range compare (b is "<X", ">=X", "<=X", ">X", "=X"): returns -1/0/1 where
+ *   -1 = a satisfies "less than b"
+ *    0 = a satisfies the expression exactly
+ *    1 = a does not satisfy (a is greater/outside the constraint)
+ *
+ * Practical contract used by sync-all filters: `compareVersions(localVersion, "<0.2") === -1`
+ * means the local version is strictly less than 0.2 (i.e. matches the filter).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function compareVersions(a, b) {
+  if (typeof b === 'string' && /^(>=|<=|>|<|=)/.test(b)) {
+    const m = b.match(/^(>=|<=|>|<|=)\s*(.+)$/);
+    if (!m) return compareSemverPair(a, b);
+    const op = m[1];
+    const ref = m[2].trim();
+    const cmp = compareSemverPair(a, ref);
+    switch (op) {
+      case '<':
+        return cmp < 0 ? -1 : 1;
+      case '<=':
+        return cmp <= 0 ? -1 : 1;
+      case '>':
+        return cmp > 0 ? -1 : 1;
+      case '>=':
+        return cmp >= 0 ? -1 : 1;
+      case '=':
+        return cmp === 0 ? 0 : 1;
+      default:
+        return cmp;
+    }
+  }
+  return compareSemverPair(a, b);
+}
+
+module.exports = {
+  getLatestVersions,
+  compareVersions,
+  refreshLatestVersions,
+  // exported for tests
+  parseSemver,
+  compareSemverPair,
+  mavenCentralLatest,
+  npmRegistryLatest,
+  githubReleasesLatest,
+  getCachePath,
+  getFallbackPath,
+};

package/dashboard/db.js

@@ -0,0 +1,199 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+const DB_PATH = path.join(os.homedir(), '.claude', 'telemetry.db');
+
+/**
+ * Open the telemetry SQLite database.
+ * Tries better-sqlite3 first; falls back to sql.js.
+ * Throws a descriptive error if both are unavailable.
+ *
+ * @param {string} [dbPath] - path to the SQLite file (defaults to ~/.claude/telemetry.db)
+ * @returns {object} database handle (better-sqlite3 or sql.js Database)
+ */
+function openDb(dbPath) {
+  const target = dbPath || DB_PATH;
+
+  // Ensure parent directory exists
+  const dir = path.dirname(target);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Attempt better-sqlite3 (synchronous, native)
+  try {
+    const BetterSqlite3 = require('better-sqlite3');
+    const db = new BetterSqlite3(target);
+    db._isBetterSqlite3 = true;
+    return db;
+  } catch {
+    // fall through to sql.js
+  }
+
+  // Attempt sql.js (WASM, no native bindings needed)
+  try {
+    const initSqlJs = require('sql.js');
+    // sql.js is async but we simulate sync by using a wrapper approach.
+    // For the dashboard use case we return a promise-aware wrapper.
+    const wasmDb = openSqlJs(target, initSqlJs);
+    return wasmDb;
+  } catch {
+    // fall through
+  }
+
+  throw new Error(
+    'Neither better-sqlite3 nor sql.js is available. ' +
+    'Run: npm install --prefix <dashboard-dir> to install dependencies.'
+  );
+}
+
+/**
+ * Open a sql.js database from file (returns a synchronous-looking wrapper).
+ * sql.js loads the WASM synchronously when initSqlJs is called with no fetch.
+ */
+function openSqlJs(dbPath, initSqlJs) {
+  // initSqlJs can be the module itself (sql.js <= 1.6) or a factory fn (sql.js >= 1.8)
+  const SqlJs = typeof initSqlJs === 'function' ? initSqlJs({ wasmBinary: null }) : initSqlJs;
+
+  let fileBuffer = null;
+  if (fs.existsSync(dbPath)) {
+    fileBuffer = fs.readFileSync(dbPath);
+  }
+
+  const db = fileBuffer ? new SqlJs.Database(fileBuffer) : new SqlJs.Database();
+  db._isSqlJs = true;
+  db._path = dbPath;
+
+  // Patch db.close to persist
+  const origClose = db.close.bind(db);
+  db.close = () => {
+    const data = db.export();
+    fs.writeFileSync(dbPath, Buffer.from(data));
+    origClose();
+  };
+
+  return db;
+}
+
+/**
+ * Create the events table and indexes if they don't exist.
+ * Also adds missing columns to existing tables (migration-safe).
+ * Works with both better-sqlite3 and sql.js handles.
+ *
+ * @param {object} db
+ */
+function initSchema(db) {
+  const ddl = `
+    CREATE TABLE IF NOT EXISTS events (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      project_path  TEXT    NOT NULL DEFAULT 'unknown',
+      project_name  TEXT    NOT NULL DEFAULT 'unknown',
+      model         TEXT    NOT NULL DEFAULT 'other',
+      input_tokens  INTEGER NOT NULL DEFAULT 0,
+      output_tokens INTEGER NOT NULL DEFAULT 0,
+      subagent_type TEXT,
+      session_id    TEXT,
+      agent_id      TEXT,
+      agent_type    TEXT,
+      ts            INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_events_ts      ON events(ts);
+    CREATE INDEX IF NOT EXISTS idx_events_project ON events(project_path);
+    CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id);
+  `;
+
+  // Idempotent migrations for DBs created by older writer versions.
+  const alters = [
+    'ALTER TABLE events ADD COLUMN session_id TEXT',
+    'ALTER TABLE events ADD COLUMN agent_id TEXT',
+    'ALTER TABLE events ADD COLUMN agent_type TEXT',
+  ];
+
+  if (db._isBetterSqlite3) {
+    db.exec(ddl);
+    for (const stmt of alters) {
+      try { db.exec(stmt); } catch { /* column exists */ }
+    }
+  } else if (db._isSqlJs) {
+    db.run(ddl);
+    for (const stmt of alters) {
+      try { db.run(stmt); } catch { /* exists */ }
+    }
+    const data = db.export();
+    fs.writeFileSync(db._path, Buffer.from(data));
+  }
+}
+
+/**
+ * Query projects active since `sinceTs` (Unix seconds).
+ * Groups by project_path, returns last seen + session count.
+ *
+ * @param {object} db
+ * @param {number} sinceTs - Unix timestamp in seconds
+ * @returns {Array<{name: string, path: string, last_seen: number, session_count: number}>}
+ */
+function queryProjects(db, sinceTs) {
+  // session_count uses COUNT(DISTINCT session_id) so multiple SubagentStop
+  // events from the same session aggregate to 1. Events with NULL session_id
+  // (older rows or non-session contexts) fall back to being counted as one
+  // session per event via COALESCE on the row id.
+  const sql = `
+    SELECT
+      project_path                                       AS path,
+      project_name                                       AS name,
+      MAX(ts)                                            AS last_seen,
+      COUNT(DISTINCT COALESCE(session_id, CAST(id AS TEXT))) AS session_count
+    FROM events
+    WHERE ts > ?
+    GROUP BY project_path
+    ORDER BY last_seen DESC
+  `;
+
+  if (db._isBetterSqlite3) {
+    return db.prepare(sql).all(sinceTs);
+  } else if (db._isSqlJs) {
+    const stmt = db.prepare(sql);
+    const rows = [];
+    stmt.bind([sinceTs]);
+    while (stmt.step()) {
+      const r = stmt.getAsObject();
+      rows.push(r);
+    }
+    stmt.free();
+    return rows;
+  }
+  return [];
+}
+
+/**
+ * Query model usage counts.
+ *
+ * @param {object} db
+ * @returns {Array<{model: string, count: number}>}
+ */
+function queryModels(db) {
+  const sql = `
+    SELECT model, COUNT(*) AS count
+    FROM events
+    GROUP BY model
+    ORDER BY count DESC
+  `;
+
+  if (db._isBetterSqlite3) {
+    return db.prepare(sql).all();
+  } else if (db._isSqlJs) {
+    const stmt = db.prepare(sql);
+    const rows = [];
+    while (stmt.step()) {
+      rows.push(stmt.getAsObject());
+    }
+    stmt.free();
+    return rows;
+  }
+  return [];
+}
+
+module.exports = { openDb, initSchema, queryProjects, queryModels };

package/dashboard/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "development-utility-kit-dashboard",
+  "version": "1.0.0",
+  "private": true,
+  "main": "server.js",
+  "dependencies": {
+    "better-sqlite3": "^12.0.0",
+    "express": "^4.18.0"
+  },
+  "optionalDependencies": {
+    "sql.js": "^1.10.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/sprint1.test.js"
+  },
+  "devDependencies": {
+    "supertest": "^7.2.2"
+  }
+}