deepdebug-local-agent 1.0.23 → 1.1.0

package/src/observability/provision.js

@@ -0,0 +1,212 @@
+/**
+ * observability/provision.js
+ *
+ * Materialises the rendered bundle under a target dir and brings the stack up
+ * with `docker compose up -d`. Idempotent: re-running re-renders the files and
+ * `up -d` reconciles (no-op when already current).
+ *
+ * The step-by-step this performs is exactly the client runbook:
+ *   1. render the bundle for this tenant (gateway URL + trigger secret + env)
+ *   2. write files to <baseDir>/deepdebug-observability/
+ *   3. write .env (Grafana admin creds, static environment label)
+ *   4. docker compose up -d
+ *   5. report container status + the (loopback) Grafana URL
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { renderBundle, COMPOSE_PROJECT } from './bundle-files.js';
+import { dockerAvailable } from './detect.js';
+
+const execAsync = promisify(exec);
+
+/** Default install root: ~/.deepdebug/observability */
+export function defaultBaseDir() {
+  return path.join(os.homedir(), '.deepdebug', 'observability');
+}
+
+/** Write the rendered file map under installDir, creating parent dirs. */
+export function writeBundle(installDir, files) {
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(installDir, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+  }
+  return installDir;
+}
+
+/**
+ * Provision the bundle.
+ *
+ * @param {object} opts
+ * @param {string} opts.gatewayUrl     e.g. https://api.visionhammer.io
+ * @param {string} opts.triggerSecret  tenant alertmanager trigger secret (vht_...)
+ * @param {string} [opts.environment]  static env label (default 'production')
+ * @param {string} [opts.grafanaUser]  Grafana admin user (default 'admin')
+ * @param {string} [opts.grafanaPassword] Grafana admin password (default generated)
+ * @param {string} [opts.baseDir]      install root (default ~/.deepdebug/observability)
+ * @param {boolean}[opts.start=true]   run `docker compose up -d`
+ */
+export async function provisionObservability(opts = {}) {
+  const {
+    gatewayUrl,
+    triggerSecret,
+    environment = 'production',
+    grafanaUser = 'admin',
+    grafanaPassword,
+    baseDir = defaultBaseDir(),
+    start = true,
+  } = opts;
+
+  if (!gatewayUrl || !triggerSecret) {
+    return { ok: false, error: 'gatewayUrl and triggerSecret are required' };
+  }
+  const invalid = validateProvisionInput({ gatewayUrl, triggerSecret, environment, grafanaUser, grafanaPassword });
+  if (invalid) {
+    return { ok: false, error: invalid };
+  }
+
+  const avail = await dockerAvailable();
+  if (!avail.docker || !avail.compose) {
+    return {
+      ok: false,
+      error: 'docker or the compose plugin is not available on this host',
+      docker: avail,
+      hint: 'install Docker Engine + the compose plugin, then retry',
+    };
+  }
+
+  const installDir = path.join(baseDir, COMPOSE_PROJECT);
+  const files = renderBundle({ gatewayUrl, triggerSecret, environment });
+  writeBundle(installDir, files);
+
+  // Grafana admin password: caller-supplied, else a random one we report back.
+  const pw = grafanaPassword || randomPassword();
+  const envFile = [
+    `GF_ADMIN_USER=${grafanaUser}`,
+    `GF_ADMIN_PASSWORD=${pw}`,
+    `DDO_ENVIRONMENT=${environment}`,
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(installDir, '.env'), envFile, 'utf8');
+
+  const result = {
+    ok: true,
+    installDir,
+    project: COMPOSE_PROJECT,
+    environment,
+    filesWritten: Object.keys(files).length,
+    grafana: { url: 'http://127.0.0.1:3000', user: grafanaUser, password: pw },
+    started: false,
+  };
+
+  if (!start) return result;
+
+  try {
+    const { stdout, stderr } = await execAsync(
+      'docker compose up -d --remove-orphans',
+      { cwd: installDir, timeout: 300000 }
+    );
+    result.started = true;
+    result.composeOutput = (stderr || stdout || '').trim().split('\n').slice(-12).join('\n');
+    result.status = await composeStatus(installDir);
+  } catch (e) {
+    result.ok = false;
+    result.started = false;
+    result.error = `docker compose up failed: ${e.message}`;
+    result.composeOutput = (e.stderr || e.stdout || '').toString().trim().split('\n').slice(-12).join('\n');
+  }
+  return result;
+}
+
+/** `docker compose ps` for the installed project, as structured rows. */
+export async function composeStatus(installDir) {
+  try {
+    const { stdout } = await execAsync('docker compose ps --format json', {
+      cwd: installDir,
+      timeout: 30000,
+    });
+    // compose emits either a JSON array or one JSON object per line.
+    const rows = [];
+    const trimmed = stdout.trim();
+    if (trimmed.startsWith('[')) {
+      for (const r of JSON.parse(trimmed)) rows.push(pickRow(r));
+    } else {
+      for (const line of trimmed.split('\n').filter(Boolean)) {
+        try { rows.push(pickRow(JSON.parse(line))); } catch { /* skip */ }
+      }
+    }
+    return rows;
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/** Tear the stack down (optionally removing data volumes). */
+export async function teardownObservability({ baseDir = defaultBaseDir(), purge = false } = {}) {
+  const installDir = path.join(baseDir, COMPOSE_PROJECT);
+  if (!fs.existsSync(path.join(installDir, 'docker-compose.yml'))) {
+    return { ok: true, note: 'nothing installed at ' + installDir };
+  }
+  try {
+    const cmd = purge ? 'docker compose down -v' : 'docker compose down';
+    const { stdout, stderr } = await execAsync(cmd, { cwd: installDir, timeout: 120000 });
+    return { ok: true, purged: purge, output: (stderr || stdout || '').trim() };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function pickRow(r) {
+  return {
+    name: r.Name || r.name,
+    service: r.Service || r.service,
+    state: r.State || r.state,
+    status: r.Status || r.status,
+    health: r.Health || r.health,
+  };
+}
+
+function randomPassword() {
+  // Reported back once; the operator may rotate it in Grafana.
+  return 'ddo-' + crypto.randomBytes(18).toString('base64url');
+}
+
+const SAFE_TOKEN = /^[A-Za-z0-9._~-]+$/;
+
+/**
+ * Every value below is written verbatim into YAML, Alloy and .env files, so a quote
+ * or newline would let a caller rewrite the config. Returns an error message or null.
+ */
+export function validateProvisionInput({ gatewayUrl, triggerSecret, environment, grafanaUser, grafanaPassword }) {
+  let url;
+  try {
+    url = new URL(String(gatewayUrl));
+  } catch {
+    return 'gatewayUrl is not a URL';
+  }
+  const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === 'host.docker.internal';
+  if (url.protocol !== 'https:' && !(local && url.protocol === 'http:')) {
+    return 'gatewayUrl must be https';
+  }
+  if (url.search || url.hash || url.username || url.password || !/^[A-Za-z0-9.:\/_-]+$/.test(String(gatewayUrl))) {
+    return 'gatewayUrl must be a plain origin (no query, credentials or special characters)';
+  }
+  if (!/^vht_[A-Za-z0-9._-]+$/.test(String(triggerSecret))) {
+    return 'triggerSecret must be a vht_ trigger secret';
+  }
+  if (environment != null && !/^[a-z0-9_-]{1,32}$/.test(String(environment))) {
+    return 'environment must match [a-z0-9_-]{1,32}';
+  }
+  if (grafanaUser != null && !SAFE_TOKEN.test(String(grafanaUser))) {
+    return 'grafanaUser contains unsupported characters';
+  }
+  if (grafanaPassword != null && grafanaPassword !== '' && !SAFE_TOKEN.test(String(grafanaPassword))) {
+    return 'grafanaPassword contains unsupported characters';
+  }
+  return null;
+}

package/src/observability/render-cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Write the client observability bundle to a directory, without starting it.
+ *
+ * Used by the self-hosted installer (gateway /api/v1/self-hosted/install.sh), which
+ * runs it inside the public agent image so the templates have one source of truth:
+ *
+ *   docker run --rm --user 0 --entrypoint node \
+ *     -e VH_GATEWAY_URL -e VH_TRIGGER_SECRET -e VH_ENVIRONMENT \
+ *     -v /opt/visionhammer/observability:/out <image> /app/src/observability/render-cli.js /out
+ *
+ * The secret comes from the environment, never argv (argv is visible in `ps`).
+ * Prints a JSON summary (including the generated Grafana password) to stdout.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { renderBundle, COMPOSE_PROJECT } from './bundle-files.js';
+import { validateProvisionInput } from './provision.js';
+
+function main() {
+  const outRoot = process.argv[2];
+  if (!outRoot) {
+    console.error('usage: render-cli.js <out-dir>   (env: VH_GATEWAY_URL, VH_TRIGGER_SECRET, VH_ENVIRONMENT)');
+    process.exit(2);
+  }
+  const gatewayUrl = process.env.VH_GATEWAY_URL;
+  const triggerSecret = process.env.VH_TRIGGER_SECRET;
+  const environment = process.env.VH_ENVIRONMENT || 'production';
+  const invalid = validateProvisionInput({ gatewayUrl, triggerSecret, environment });
+  if (invalid) {
+    console.error(`render-cli: ${invalid}`);
+    process.exit(2);
+  }
+
+  const dir = path.join(outRoot, COMPOSE_PROJECT);
+  const files = renderBundle({ gatewayUrl, triggerSecret, environment });
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf8');
+  }
+  const grafanaPassword = 'ddo-' + crypto.randomBytes(18).toString('base64url');
+  fs.writeFileSync(path.join(dir, '.env'),
+    `GF_ADMIN_USER=admin\nGF_ADMIN_PASSWORD=${grafanaPassword}\nDDO_ENVIRONMENT=${environment}\n`,
+    { encoding: 'utf8', mode: 0o600 });
+  // The bundle holds the trigger secret: keep it root-only on the host.
+  fs.chmodSync(dir, 0o700);
+
+  process.stdout.write(JSON.stringify({
+    ok: true,
+    dir,
+    project: COMPOSE_PROJECT,
+    files: Object.keys(files).length,
+    grafana: { url: 'http://127.0.0.1:3000', user: 'admin', password: grafanaPassword },
+  }) + '\n');
+}
+
+main();

package/src/observability/routes.js

@@ -0,0 +1,88 @@
+/**
+ * observability/routes.js
+ *
+ * Local-agent HTTP surface for the "zero observability -> provision" flow the
+ * gateway drives during onboarding.
+ *
+ *   GET  /observability/status      probe the host; classify; recommend
+ *   POST /observability/provision   apply the bundle (guarded: skips if the
+ *                                    client already has a stack, unless force)
+ *   POST /observability/teardown    docker compose down (optionally -v)
+ *
+ * Mount in server.js with:
+ *   import { registerObservabilityRoutes } from './observability/routes.js';
+ *   registerObservabilityRoutes(app);
+ */
+
+import { detectObservability } from './detect.js';
+import { provisionObservability, teardownObservability, validateProvisionInput } from './provision.js';
+
+export function registerObservabilityRoutes(app) {
+  // ---- GET /observability/status ----
+  app.get('/observability/status', async (_req, res) => {
+    try {
+      const probe = await detectObservability();
+      res.json({ ok: true, ...probe });
+    } catch (e) {
+      console.error('[Observability] status failed:', e.message);
+      res.status(500).json({ ok: false, error: e.message });
+    }
+  });
+
+  // ---- POST /observability/provision ----
+  // Body: { gatewayUrl, triggerSecret, environment?, grafanaUser?,
+  //         grafanaPassword?, force?, start? }
+  app.post('/observability/provision', async (req, res) => {
+    const {
+      gatewayUrl, triggerSecret, environment,
+      grafanaUser, grafanaPassword, force = false, start = true,
+    } = req.body || {};
+
+    if (!gatewayUrl || !triggerSecret) {
+      return res.status(400).json({ ok: false, error: 'gatewayUrl and triggerSecret are required' });
+    }
+    const invalid = validateProvisionInput({ gatewayUrl, triggerSecret, environment, grafanaUser, grafanaPassword });
+    if (invalid) {
+      return res.status(400).json({ ok: false, error: invalid });
+    }
+
+    try {
+      // Guard: never deploy on top of an existing stack unless explicitly forced.
+      // Our own already-running stack does NOT block (re-provision is idempotent).
+      const probe = await detectObservability();
+      if (probe.hasObservability && !probe.ownStackRunning && !force) {
+        return res.status(409).json({
+          ok: false,
+          skipped: true,
+          reason: 'client already has observability',
+          found: probe.found,
+          hint: 'pass force:true to provision anyway',
+        });
+      }
+
+      console.log(`[Observability] Provisioning bundle (env=${environment || 'production'}, force=${force})`);
+      const result = await provisionObservability({
+        gatewayUrl, triggerSecret, environment, grafanaUser, grafanaPassword, start,
+      });
+      result.detectedBefore = { found: probe.found, hadObservability: probe.hasObservability };
+      return res.status(result.ok ? 200 : 500).json(result);
+    } catch (e) {
+      console.error('[Observability] provision failed:', e.message);
+      return res.status(500).json({ ok: false, error: e.message });
+    }
+  });
+
+  // ---- POST /observability/teardown ----
+  app.post('/observability/teardown', async (req, res) => {
+    const { purge = false } = req.body || {};
+    try {
+      const result = await teardownObservability({ purge });
+      res.status(result.ok ? 200 : 500).json(result);
+    } catch (e) {
+      console.error('[Observability] teardown failed:', e.message);
+      res.status(500).json({ ok: false, error: e.message });
+    }
+  });
+
+  console.log('[Observability] routes registered: /observability/{status,provision,teardown}');
+}

package/src/patch/patch-engine.js

@@ -4,12 +4,12 @@ import { readFile, writeFile, exists, ensureDir, copyFile } from '../utils/fs-ut
 /**
  * PatchEngine
  *
- * Sistema de aplicação de patches com backup e rollback.
+ * Patch application system with backup and rollback.
  */
 
 /**
- * Parseia unified diff
- * @param {string} diffText - Texto do diff
+ * Parses a unified diff
+ * @param {string} diffText - Diff text
  * @returns {Patch[]}
  */
 export function parsePatch(diffText) {
@@ -22,7 +22,7 @@ export function parsePatch(diffText) {
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
 
-        // Início de novo arquivo
+        // Start of a new file
         if (line.startsWith('---')) {
             if (currentPatch) {
                 patches.push(currentPatch);
@@ -35,12 +35,12 @@ export function parsePatch(diffText) {
             };
         }
 
-        // Nome do novo arquivo
+        // Name of the new file
         else if (line.startsWith('+++') && currentPatch) {
             currentPatch.newFileName = extractFileName(line);
         }
 
-        // Início de hunk
+        // Start of a hunk
         else if (line.startsWith('@@') && currentPatch) {
             const hunkMatch = line.match(/@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@/);
 
@@ -56,7 +56,7 @@ export function parsePatch(diffText) {
             }
         }
 
-        // Linha de conteúdo do hunk
+        // Content line of the hunk
         else if (currentHunk && (line.startsWith(' ') || line.startsWith('+') || line.startsWith('-'))) {
             currentHunk.lines.push(line);
         }
@@ -70,16 +70,16 @@ export function parsePatch(diffText) {
 }
 
 /**
- * Extrai nome do arquivo da linha --- ou +++
+ * Extracts the file name from the --- or +++ line
  */
 function extractFileName(line) {
     return line.replace(/^[-+]{3}\s+[ab]\//, '').replace(/^[-+]{3}\s+/, '');
 }
 
 /**
- * Aplica patch a um arquivo
- * @param {string} original - Conteúdo original
- * @param {Patch} patch - Patch a aplicar
+ * Applies a patch to a file
+ * @param {string} original - Original content
+ * @param {Patch} patch - Patch to apply
  * @returns {string|false}
  */
 export function applyPatch(original, patch) {
@@ -94,7 +94,7 @@ export function applyPatch(original, patch) {
         let removedCount = 0;
         let addedCount = 0;
 
-        // Verificar contexto
+        // Check the context
         let contextMatches = true;
         let checkLine = startLine;
 
@@ -118,7 +118,7 @@ export function applyPatch(original, patch) {
             return false;
         }
 
-        // Aplicar hunk
+        // Apply the hunk
         const linesToRemove = [];
         const linesToAdd = [];
 
@@ -138,12 +138,12 @@ export function applyPatch(original, patch) {
             }
         }
 
-        // Remover linhas (de trás para frente)
+        // Remove lines (back to front)
         for (let i = linesToRemove.length - 1; i >= 0; i--) {
             resultLines.splice(linesToRemove[i], 1);
         }
 
-        // Adicionar linhas
+        // Add lines
         for (let i = 0; i < linesToAdd.length; i++) {
             const { position, content } = linesToAdd[i];
             const adjustedPosition = position - removedCount + i;
@@ -157,9 +157,9 @@ export function applyPatch(original, patch) {
 }
 
 /**
- * Aplica unified diff a um workspace
- * @param {string} root - Raiz do workspace
- * @param {string} diffText - Texto do diff
+ * Applies a unified diff to a workspace
+ * @param {string} root - Workspace root
+ * @param {string} diffText - Diff text
  * @returns {Promise<PatchResult>}
  */
 export async function applyUnifiedDiff(root, diffText) {
@@ -231,10 +231,10 @@ export async function applyUnifiedDiff(root, diffText) {
 }
 
 /**
- * Cria backup de arquivos antes de aplicar patch
- * @param {string} root - Raiz do workspace
- * @param {string[]} files - Lista de arquivos
- * @param {string} backupId - ID do backup
+ * Creates a backup of files before applying a patch
+ * @param {string} root - Workspace root
+ * @param {string[]} files - List of files
+ * @param {string} backupId - Backup ID
  * @returns {Promise<BackupResult>}
  */
 export async function createBackup(root, files, backupId) {
@@ -254,7 +254,7 @@ export async function createBackup(root, files, backupId) {
         }
     }
 
-    // Criar manifest
+    // Create the manifest
     const manifest = {
         id: backupId,
         timestamp: new Date().toISOString(),
@@ -275,9 +275,9 @@ export async function createBackup(root, files, backupId) {
 }
 
 /**
- * Restaura backup
- * @param {string} root - Raiz do workspace
- * @param {string} backupId - ID do backup
+ * Restores a backup
+ * @param {string} root - Workspace root
+ * @param {string} backupId - Backup ID
  * @returns {Promise<RestoreResult>}
  */
 export async function restoreBackup(root, backupId) {
@@ -309,8 +309,8 @@ export async function restoreBackup(root, backupId) {
 }
 
 /**
- * Extrai arquivos afetados por um diff
- * @param {string} diffText - Texto do diff
+ * Extracts the files affected by a diff
+ * @param {string} diffText - Diff text
  * @returns {string[]}
  */
 export function extractAffectedFiles(diffText) {