chore: sync workspace — configs, docs, scripts, CI, pnpm, submodules

- Submodule pins: dbis_core, cross-chain-pmm-lps, mcp-proxmox (local, push may be pending), metamask-integration, smom-dbis-138 - Atomic swap + cross-chain-pmm-lops-publish, deploy-portal workflow, phoenix deploy-targets, routing/aggregator matrices - Docs, token-lists, forge proxy, phoenix API, runbooks, verify scripts Made-with: Cursor
2026-04-21 22:01:33 -07:00
parent e6bc7a6d7c
commit b8613905bd
231 changed files with 31657 additions and 2184 deletions
--- a/phoenix-deploy-api/server.js
+++ b/phoenix-deploy-api/server.js
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Phoenix Deploy API — Gitea webhook receiver, deploy stub, and Phoenix API Railing (Infra/VE)
+ * Phoenix Deploy API — Gitea webhook receiver, deploy execution API, and Phoenix API Railing (Infra/VE)
 *
 * Endpoints:
 *   POST /webhook/gitea   — Receives Gitea push/tag/PR webhooks
@@ -19,6 +19,8 @@
 import crypto from 'crypto';
 import https from 'https';
 import path from 'path';
+import { promisify } from 'util';
+import { execFile as execFileCallback } from 'child_process';
 import { readFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
 import express from 'express';
@@ -42,6 +44,13 @@ const PROMETHEUS_URL = (process.env.PROMETHEUS_URL || 'http://localhost:9090').r
 const PHOENIX_WEBHOOK_URL = process.env.PHOENIX_WEBHOOK_URL || '';
 const PHOENIX_WEBHOOK_SECRET = process.env.PHOENIX_WEBHOOK_SECRET || '';
 const PARTNER_KEYS = (process.env.PHOENIX_PARTNER_KEYS || '').split(',').map((k) => k.trim()).filter(Boolean);
+const WEBHOOK_DEPLOY_ENABLED = process.env.PHOENIX_WEBHOOK_DEPLOY_ENABLED === '1' || process.env.PHOENIX_WEBHOOK_DEPLOY_ENABLED === 'true';
+const execFile = promisify(execFileCallback);
+
+function expandEnvTokens(value) {
+  if (typeof value !== 'string') return value;
+  return value.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, key) => process.env[key] || '');
+}

 /**
 * Manifest resolution order:
@@ -63,15 +72,249 @@ function resolvePublicSectorManifestPath() {
  return path.join(__dirname, '..', 'config', 'public-sector-program-manifest.json');
 }

+function resolveDeployTargetsPath() {
+  const override = (process.env.DEPLOY_TARGETS_PATH || '').trim();
+  if (override && existsSync(override)) return override;
+  const bundled = path.join(__dirname, 'deploy-targets.json');
+  if (existsSync(bundled)) return bundled;
+  return bundled;
+}
+
+function loadDeployTargetsConfig() {
+  const configPath = resolveDeployTargetsPath();
+  if (!existsSync(configPath)) {
+    return {
+      path: configPath,
+      defaults: {},
+      targets: [],
+    };
+  }
+  const raw = readFileSync(configPath, 'utf8');
+  const parsed = JSON.parse(raw);
+  return {
+    path: configPath,
+    defaults: parsed.defaults || {},
+    targets: Array.isArray(parsed.targets) ? parsed.targets : [],
+  };
+}
+
+function findDeployTarget(repo, branch, requestedTarget) {
+  const config = loadDeployTargetsConfig();
+  const wantedTarget = requestedTarget || 'default';
+  const match = config.targets.find((entry) => {
+    if (entry.repo !== repo) return false;
+    if ((entry.branch || 'main') !== branch) return false;
+    return (entry.target || 'default') === wantedTarget;
+  });
+  return { config, match, wantedTarget };
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function verifyHealthCheck(healthcheck) {
+  if (!healthcheck || !healthcheck.url) return null;
+
+  const attempts = Math.max(1, Number(healthcheck.attempts || 1));
+  const delayMs = Math.max(0, Number(healthcheck.delay_ms || 0));
+  const timeoutMs = Math.max(1000, Number(healthcheck.timeout_ms || 10000));
+  const expectedStatus = Number(healthcheck.expect_status || 200);
+  const expectBodyIncludes = healthcheck.expect_body_includes || '';
+
+  let lastError = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      const res = await fetch(healthcheck.url, { signal: controller.signal });
+      const body = await res.text();
+      clearTimeout(timeout);
+
+      if (res.status !== expectedStatus) {
+        throw new Error(`Expected HTTP ${expectedStatus}, got ${res.status}`);
+      }
+      if (expectBodyIncludes && !body.includes(expectBodyIncludes)) {
+        throw new Error(`Health body missing expected text: ${expectBodyIncludes}`);
+      }
+
+      return {
+        ok: true,
+        url: healthcheck.url,
+        status: res.status,
+        attempt,
+      };
+    } catch (err) {
+      lastError = err;
+      if (attempt < attempts && delayMs > 0) {
+        await sleep(delayMs);
+      }
+    }
+  }
+
+  throw new Error(`Health check failed for ${healthcheck.url}: ${lastError?.message || 'unknown error'}`);
+}
+
+async function runDeployTarget(definition, configDefaults, context) {
+  if (!Array.isArray(definition.command) || definition.command.length === 0) {
+    throw new Error('Deploy target is missing a command array');
+  }
+
+  const cwd = expandEnvTokens(definition.cwd || configDefaults.cwd || process.cwd());
+  const timeoutSeconds = Number(definition.timeout_sec || configDefaults.timeout_sec || 1800);
+  const timeout = Number.isFinite(timeoutSeconds) && timeoutSeconds > 0 ? timeoutSeconds * 1000 : 1800 * 1000;
+  const command = definition.command.map((part) => expandEnvTokens(part));
+  const missingEnv = (definition.required_env || []).filter((key) => !process.env[key]);
+  if (missingEnv.length > 0) {
+    throw new Error(`Missing required env for deploy target: ${missingEnv.join(', ')}`);
+  }
+  if (!existsSync(cwd)) {
+    throw new Error(`Deploy working directory does not exist: ${cwd}`);
+  }
+
+  const childEnv = {
+    ...process.env,
+    PHOENIX_DEPLOY_REPO: context.repo,
+    PHOENIX_DEPLOY_BRANCH: context.branch,
+    PHOENIX_DEPLOY_SHA: context.sha || '',
+    PHOENIX_DEPLOY_TARGET: context.target,
+    PHOENIX_DEPLOY_TRIGGER: context.trigger,
+  };
+
+  const { stdout, stderr } = await execFile(command[0], command.slice(1), {
+    cwd,
+    env: childEnv,
+    timeout,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  const healthcheck = await verifyHealthCheck(definition.healthcheck || configDefaults.healthcheck || null);
+
+  return {
+    cwd,
+    command,
+    stdout: stdout || '',
+    stderr: stderr || '',
+    timeout_sec: timeoutSeconds,
+    healthcheck,
+  };
+}
+
+async function executeDeploy({ repo, branch = 'main', target = 'default', sha = '', trigger = 'api' }) {
+  if (!repo) {
+    const error = new Error('repo required');
+    error.statusCode = 400;
+    error.payload = { error: error.message };
+    throw error;
+  }
+
+  const [owner, repoName] = repo.includes('/') ? repo.split('/') : ['d-bis', repo];
+  const commitSha = sha || '';
+  const requestedTarget = target || 'default';
+  const { config, match, wantedTarget } = findDeployTarget(repo, branch, requestedTarget);
+
+  if (!match) {
+    const error = new Error('Deploy target not configured');
+    error.statusCode = 404;
+    error.payload = {
+      error: error.message,
+      repo,
+      branch,
+      target: wantedTarget,
+      config_path: config.path,
+    };
+    if (commitSha && GITEA_TOKEN) {
+      await setGiteaCommitStatus(owner, repoName, commitSha, 'failure', `No deploy target for ${repo} ${branch} ${wantedTarget}`);
+    }
+    throw error;
+  }
+
+  if (commitSha && GITEA_TOKEN) {
+    await setGiteaCommitStatus(owner, repoName, commitSha, 'pending', 'Phoenix deployment in progress');
+  }
+
+  console.log(`[deploy] ${repo} branch=${branch} target=${wantedTarget} sha=${commitSha} trigger=${trigger}`);
+
+  let deployResult = null;
+  let deployError = null;
+
+  try {
+    deployResult = await runDeployTarget(match, config.defaults, {
+      repo,
+      branch,
+      sha: commitSha,
+      target: wantedTarget,
+      trigger,
+    });
+    if (commitSha && GITEA_TOKEN) {
+      await setGiteaCommitStatus(owner, repoName, commitSha, 'success', `Deployed to ${wantedTarget}`);
+    }
+    return {
+      status: 'completed',
+      repo,
+      branch,
+      target: wantedTarget,
+      config_path: config.path,
+      command: deployResult.command,
+      cwd: deployResult.cwd,
+      stdout: deployResult.stdout,
+      stderr: deployResult.stderr,
+      healthcheck: deployResult.healthcheck,
+    };
+  } catch (err) {
+    deployError = err;
+    if (commitSha && GITEA_TOKEN) {
+      await setGiteaCommitStatus(owner, repoName, commitSha, 'failure', `Deploy failed: ${err.message.slice(0, 120)}`);
+    }
+    err.statusCode = err.statusCode || 500;
+    err.payload = err.payload || {
+      error: err.message,
+      repo,
+      branch,
+      target: wantedTarget,
+      config_path: config.path,
+    };
+    throw err;
+  } finally {
+    if (PHOENIX_WEBHOOK_URL) {
+      const payload = {
+        event: 'deploy.completed',
+        repo,
+        branch,
+        target: wantedTarget,
+        sha: commitSha,
+        success: Boolean(deployResult),
+        command: deployResult?.command,
+        cwd: deployResult?.cwd,
+        error: deployError?.message || null,
+      };
+      const body = JSON.stringify(payload);
+      const sig = crypto.createHmac('sha256', PHOENIX_WEBHOOK_SECRET || '').update(body).digest('hex');
+      fetch(PHOENIX_WEBHOOK_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Phoenix-Signature': `sha256=${sig}` },
+        body,
+      }).catch((e) => console.error('[webhook] outbound failed', e.message));
+    }
+  }
+}
+
 const httpsAgent = new https.Agent({ rejectUnauthorized: process.env.PROXMOX_TLS_VERIFY !== '0' });

+function formatProxmoxAuthHeader(user, tokenName, tokenValue) {
+  if (tokenName.includes('!')) {
+    return `PVEAPIToken=${tokenName}=${tokenValue}`;
+  }
+  return `PVEAPIToken=${user}!${tokenName}=${tokenValue}`;
+}
+
 async function proxmoxRequest(endpoint, method = 'GET', body = null) {
  const baseUrl = `https://${PROXMOX_HOST}:${PROXMOX_PORT}/api2/json`;
  const url = `${baseUrl}${endpoint}`;
  const options = {
    method,
    headers: {
-      Authorization: `PVEAPIToken=${PROXMOX_USER}!${PROXMOX_TOKEN_NAME}=${PROXMOX_TOKEN_VALUE}`,
+      Authorization: formatProxmoxAuthHeader(PROXMOX_USER, PROXMOX_TOKEN_NAME, PROXMOX_TOKEN_VALUE),
      'Content-Type': 'application/json',
    },
    agent: httpsAgent,
@@ -162,12 +405,44 @@ app.post('/webhook/gitea', async (req, res) => {

  if (action === 'push' || (action === 'synchronize' && payload.pull_request)) {
    if (branch === 'main' || branch === 'master' || ref.startsWith('refs/tags/')) {
-      if (sha && GITEA_TOKEN) {
-        await setGiteaCommitStatus(owner, repoName, sha, 'pending', 'Phoenix deployment triggered');
+      if (!WEBHOOK_DEPLOY_ENABLED) {
+        return res.status(200).json({
+          received: true,
+          repo: fullName,
+          branch,
+          sha,
+          deployed: false,
+          message: 'Webhook accepted; set PHOENIX_WEBHOOK_DEPLOY_ENABLED=1 to execute deploys from webhook events.',
+        });
+      }
+
+      try {
+        const result = await executeDeploy({
+          repo: fullName,
+          branch,
+          sha,
+          target: 'default',
+          trigger: 'webhook',
+        });
+        return res.status(200).json({
+          received: true,
+          repo: fullName,
+          branch,
+          sha,
+          deployed: true,
+          result,
+        });
+      } catch (err) {
+        return res.status(200).json({
+          received: true,
+          repo: fullName,
+          branch,
+          sha,
+          deployed: false,
+          error: err.message,
+          details: err.payload || null,
+        });
      }
-      // Stub: enqueue deploy; actual implementation would call Proxmox/deploy logic
-      console.log(`[deploy-stub] Would deploy ${fullName} branch=${branch} sha=${sha}`);
-      // Stub: when full deploy runs, call setGiteaCommitStatus(owner, repoName, sha, 'success'|'failure', ...)
    }
  }

@@ -185,47 +460,36 @@ app.post('/api/deploy', async (req, res) => {
  }

  const { repo, branch = 'main', target, sha } = req.body;
-  if (!repo) {
-    return res.status(400).json({ error: 'repo required' });
+  try {
+    const result = await executeDeploy({
+      repo,
+      branch,
+      sha,
+      target,
+      trigger: 'api',
+    });
+    res.status(200).json(result);
+  } catch (err) {
+    res.status(err.statusCode || 500).json(err.payload || { error: err.message });
  }
+});

-  const [owner, repoName] = repo.includes('/') ? repo.split('/') : ['d-bis', repo];
-  const commitSha = sha || '';
-
-  if (commitSha && GITEA_TOKEN) {
-    await setGiteaCommitStatus(owner, repoName, commitSha, 'pending', 'Phoenix deployment in progress');
-  }
-
-  console.log(`[deploy] ${repo} branch=${branch} target=${target || 'default'} sha=${commitSha}`);
-  // Stub: no real deploy yet — report success so Gitea shows green; replace with real deploy + setGiteaCommitStatus on completion
-  const deploySuccess = true;
-  if (commitSha && GITEA_TOKEN) {
-    await setGiteaCommitStatus(
-      owner,
-      repoName,
-      commitSha,
-      deploySuccess ? 'success' : 'failure',
-      deploySuccess ? 'Deploy accepted (stub)' : 'Deploy failed (stub)'
-    );
-  }
-  res.status(202).json({
-    status: 'accepted',
-    repo,
-    branch,
-    target: target || 'default',
-    message: 'Deploy request queued (stub). Implement full deploy logic in Sankofa Phoenix API.',
+app.get('/api/deploy-targets', (req, res) => {
+  const config = loadDeployTargetsConfig();
+  const targets = config.targets.map((entry) => ({
+    repo: entry.repo,
+    branch: entry.branch || 'main',
+    target: entry.target || 'default',
+    description: entry.description || '',
+    cwd: entry.cwd || config.defaults.cwd || '',
+    command: entry.command || [],
+    has_healthcheck: Boolean(entry.healthcheck || config.defaults.healthcheck),
+  }));
+  res.json({
+    config_path: config.path,
+    count: targets.length,
+    targets,
  });
-
-  if (PHOENIX_WEBHOOK_URL) {
-    const payload = { event: 'deploy.completed', repo, branch, target: target || 'default', sha: commitSha, success: deploySuccess };
-    const body = JSON.stringify(payload);
-    const sig = crypto.createHmac('sha256', PHOENIX_WEBHOOK_SECRET || '').update(body).digest('hex');
-    fetch(PHOENIX_WEBHOOK_URL, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'X-Phoenix-Signature': `sha256=${sig}` },
-      body,
-    }).catch((e) => console.error('[webhook] outbound failed', e.message));
-  }
 });

 /**
@@ -474,7 +738,10 @@ app.listen(PORT, () => {
  if (!GITEA_TOKEN) console.warn('GITEA_TOKEN not set — commit status updates disabled');
  if (!hasProxmox) console.warn('PROXMOX_* not set — Infra/VE API returns stub data');
  if (PHOENIX_WEBHOOK_URL) console.log('Outbound webhook enabled:', PHOENIX_WEBHOOK_URL);
+  if (WEBHOOK_DEPLOY_ENABLED) console.log('Inbound webhook deploy execution enabled');
  if (PARTNER_KEYS.length > 0) console.log('Partner API key auth enabled for /api/v1/* (except GET /api/v1/public-sector/programs)');
  const mpath = resolvePublicSectorManifestPath();
+  const dpath = resolveDeployTargetsPath();
  console.log(`Public-sector manifest: ${mpath} (${existsSync(mpath) ? 'ok' : 'missing'})`);
+  console.log(`Deploy targets: ${dpath} (${existsSync(dpath) ? 'ok' : 'missing'})`);
 });