@nexussdk/flags 0.0.1 → 0.0.4

package/dist/chunk-VC3UFQ47.mjs

@@ -0,0 +1,767 @@
+#!/usr/bin/env node
+
+// src/dev-server/flag-store.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+var DevFlagStore = class {
+  _flags = {};
+  _filePath;
+  constructor(filePath) {
+    this._filePath = path.resolve(filePath);
+    this._load();
+  }
+  getAll() {
+    return Object.values(this._flags).sort(
+      (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+    );
+  }
+  getByKey(key) {
+    return this._flags[key];
+  }
+  size() {
+    return Object.keys(this._flags).length;
+  }
+  /** Evaluation-compatible bootstrap snapshot */
+  getBootstrapSnapshot() {
+    const out = {};
+    for (const [key, flag] of Object.entries(this._flags)) {
+      out[key] = {
+        enabled: flag.enabled,
+        variants: flag.variants,
+        reason: flag.enabled ? "EXPLICITLY_INCLUDED" : "DISABLED"
+      };
+    }
+    return out;
+  }
+  create(data) {
+    if (this._flags[data.key]) {
+      throw new Error(`Flag with key "${data.key}" already exists.`);
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const flag = {
+      key: data.key,
+      name: data.name ?? data.key,
+      enabled: data.enabled ?? false,
+      description: data.description ?? "",
+      rolloutPercentage: data.rolloutPercentage ?? 100,
+      variants: data.variants ?? {},
+      createdAt: now,
+      updatedAt: now
+    };
+    this._flags[data.key] = flag;
+    this._persist();
+    return flag;
+  }
+  update(key, patch) {
+    const existing = this._flags[key];
+    if (!existing) throw new Error(`Flag "${key}" not found.`);
+    const updated = { ...existing, ...patch, key, createdAt: existing.createdAt, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    this._flags[key] = updated;
+    this._persist();
+    return updated;
+  }
+  delete(key) {
+    if (!this._flags[key]) return false;
+    delete this._flags[key];
+    this._persist();
+    return true;
+  }
+  toggle(key) {
+    const flag = this._flags[key];
+    if (!flag) throw new Error(`Flag "${key}" not found.`);
+    return this.update(key, { enabled: !flag.enabled });
+  }
+  seedIfEmpty() {
+    if (this.size() > 0) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const seeds = [
+      { key: "dark_mode", name: "Dark Mode", enabled: true, description: "Toggle dark/light theme.", rolloutPercentage: 100, variants: { theme: "dark" }, createdAt: now, updatedAt: now },
+      { key: "new_checkout", name: "New Checkout Flow", enabled: false, description: "Redesigned checkout UI.", rolloutPercentage: 50, variants: { discount: 10, layout: "single-page" }, createdAt: now, updatedAt: now },
+      { key: "beta_dashboard", name: "Beta Dashboard", enabled: false, description: "New analytics dashboard (internal beta).", rolloutPercentage: 0, variants: {}, createdAt: now, updatedAt: now }
+    ];
+    for (const flag of seeds) {
+      this._flags[flag.key] = flag;
+    }
+    this._persist();
+  }
+  _load() {
+    try {
+      if (fs.existsSync(this._filePath)) {
+        const raw = fs.readFileSync(this._filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        for (const [k, v] of Object.entries(parsed)) {
+          if (v && typeof v === "object" && "key" in v) {
+            this._flags[k] = v;
+          }
+        }
+      }
+    } catch {
+      this._flags = {};
+    }
+  }
+  _persist() {
+    try {
+      const dir = path.dirname(this._filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this._filePath, JSON.stringify(this._flags, null, 2), "utf8");
+    } catch {
+    }
+  }
+};
+
+// src/dev-server/sse.ts
+var FlagSseBroadcaster = class {
+  _clients = /* @__PURE__ */ new Set();
+  _heartbeatInterval = null;
+  constructor() {
+    this._startHeartbeat();
+  }
+  addClient(res) {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "Access-Control-Allow-Origin": "*",
+      "X-Accel-Buffering": "no"
+    });
+    res.write(`: connected
+data: ${JSON.stringify({ timestamp: Date.now() })}
+
+`);
+    this._clients.add(res);
+    res.on("close", () => {
+      this._clients.delete(res);
+    });
+    res.on("error", () => {
+      this._clients.delete(res);
+    });
+  }
+  /**
+   * Broadcasts a FLAG_UPDATE event - SDK client receives and re-evaluates the flag.
+   */
+  broadcastFlagUpdate(key, enabled, variants) {
+    const streamEvent = {
+      type: "FLAG_UPDATE",
+      key,
+      data: {
+        key,
+        enabled,
+        variants,
+        reason: enabled ? "DEFAULT_ENABLED" : "KILL_SWITCH",
+        version: 1
+      },
+      timestamp: Date.now()
+    };
+    this._broadcast("FLAG_UPDATE", streamEvent);
+  }
+  /**
+   * Broadcasts a FLAG_DELETE event - SDK client removes from cache.
+   */
+  broadcastFlagDelete(key) {
+    const streamEvent = {
+      type: "FLAG_DELETE",
+      key,
+      timestamp: Date.now()
+    };
+    this._broadcast("FLAG_DELETE", streamEvent);
+  }
+  get clientCount() {
+    return this._clients.size;
+  }
+  destroy() {
+    if (this._heartbeatInterval) {
+      clearInterval(this._heartbeatInterval);
+      this._heartbeatInterval = null;
+    }
+    for (const client of this._clients) {
+      try {
+        client.end();
+      } catch {
+      }
+    }
+    this._clients.clear();
+  }
+  _broadcast(eventName, data) {
+    const payload = `event: ${eventName}
+data: ${JSON.stringify(data)}
+
+`;
+    for (const client of this._clients) {
+      try {
+        client.write(payload);
+      } catch {
+        this._clients.delete(client);
+      }
+    }
+  }
+  _startHeartbeat() {
+    this._heartbeatInterval = setInterval(() => {
+      const ping = `: ping ${Date.now()}
+
+`;
+      for (const client of this._clients) {
+        try {
+          client.write(ping);
+        } catch {
+          this._clients.delete(client);
+        }
+      }
+    }, 15e3);
+    const interval = this._heartbeatInterval;
+    if (interval && typeof interval === "object" && "unref" in interval && typeof interval.unref === "function") {
+      interval.unref();
+    }
+  }
+};
+
+// src/dev-server/server.ts
+import { createServer } from "http";
+import { URL } from "url";
+
+// src/dev-server/gui.ts
+function renderFlagsGuiHtml(port) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Nexus Feature Flags Dev Server</title>
+  <style>
+    :root {
+      --bg: #090d16; --card-bg: #111827; --border: #1f2937; --border-focus: #374151;
+      --text: #f3f4f6; --text-muted: #9ca3af; --accent: #8b5cf6; --accent-hover: #7c3aed;
+      --green: #10b981; --red: #ef4444; --yellow: #f59e0b; --code-bg: #030712;
+      --radius: 8px; --toggle-off: #374151; --toggle-on: #8b5cf6;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, sans-serif; background: var(--bg); color: var(--text); min-height: 100vh; }
+    header { background: rgba(17,24,39,0.9); backdrop-filter: blur(8px); border-bottom: 1px solid var(--border); padding: 14px 24px; display: flex; align-items: center; justify-content: space-between; position: sticky; top: 0; z-index: 50; }
+    .brand { display: flex; align-items: center; gap: 10px; }
+    .brand-icon { width: 32px; height: 32px; background: linear-gradient(135deg, #8b5cf6, #6d28d9); border-radius: 8px; display: flex; align-items: center; justify-content: center; font-size: 16px; }
+    .brand-name { font-size: 0.95rem; font-weight: 700; letter-spacing: -0.02em; }
+    .brand-sub { font-size: 0.7rem; color: var(--text-muted); margin-top: 1px; }
+    .header-meta { display: flex; align-items: center; gap: 16px; }
+    .status-badge { display: flex; align-items: center; gap: 6px; font-size: 0.75rem; color: var(--green); }
+    .status-dot { width: 7px; height: 7px; background: var(--green); border-radius: 50%; animation: pulse 2s infinite; }
+    @keyframes pulse { 0%,100%{opacity:1;} 50%{opacity:0.4;} }
+    .sse-counter { font-size: 0.72rem; color: var(--text-muted); }
+    main { max-width: 960px; margin: 0 auto; padding: 32px 24px; }
+    .page-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 24px; }
+    .page-title { font-size: 1.35rem; font-weight: 700; }
+    .page-title span { color: var(--accent); }
+    .btn { display: inline-flex; align-items: center; gap: 6px; padding: 8px 16px; border-radius: var(--radius); border: none; cursor: pointer; font-size: 0.8rem; font-weight: 600; transition: all 0.15s; }
+    .btn-primary { background: var(--accent); color: #fff; }
+    .btn-primary:hover { background: var(--accent-hover); }
+    .btn-sm { padding: 4px 10px; font-size: 0.72rem; }
+    .btn-danger { background: transparent; border: 1px solid #374151; color: var(--red); }
+    .btn-danger:hover { border-color: var(--red); background: rgba(239,68,68,0.08); }
+    .btn-ghost { background: transparent; border: 1px solid var(--border); color: var(--text-muted); }
+    .btn-ghost:hover { border-color: var(--border-focus); color: var(--text); }
+    .stats-bar { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-bottom: 24px; }
+    .stat-card { background: var(--card-bg); border: 1px solid var(--border); border-radius: var(--radius); padding: 14px 18px; }
+    .stat-label { font-size: 0.72rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.06em; }
+    .stat-value { font-size: 1.5rem; font-weight: 700; margin-top: 4px; }
+    .stat-value.green { color: var(--green); }
+    .stat-value.red { color: var(--red); }
+    .flag-list { display: flex; flex-direction: column; gap: 12px; }
+    .flag-card { background: var(--card-bg); border: 1px solid var(--border); border-radius: var(--radius); padding: 18px 20px; transition: border-color 0.15s; }
+    .flag-card:hover { border-color: var(--border-focus); }
+    .flag-card.enabled { border-left: 3px solid var(--green); }
+    .flag-card.disabled { border-left: 3px solid var(--border); }
+    .flag-top { display: flex; align-items: center; justify-content: space-between; }
+    .flag-info { flex: 1; min-width: 0; }
+    .flag-key { font-family: 'SF Mono', 'Fira Code', Consolas, monospace; font-size: 0.85rem; font-weight: 600; color: var(--accent); }
+    .flag-name { font-size: 1rem; font-weight: 600; margin-top: 2px; }
+    .flag-desc { font-size: 0.8rem; color: var(--text-muted); margin-top: 4px; }
+    .flag-actions { display: flex; align-items: center; gap: 10px; flex-shrink: 0; }
+    .toggle { position: relative; width: 44px; height: 24px; cursor: pointer; }
+    .toggle input { opacity: 0; width: 0; height: 0; }
+    .toggle-slider { position: absolute; inset: 0; background: var(--toggle-off); border-radius: 24px; transition: 0.2s; }
+    .toggle-slider:before { content: ''; position: absolute; width: 18px; height: 18px; left: 3px; top: 3px; background: #fff; border-radius: 50%; transition: 0.2s; }
+    input:checked + .toggle-slider { background: var(--toggle-on); }
+    input:checked + .toggle-slider:before { transform: translateX(20px); }
+    .flag-meta { display: flex; align-items: center; gap: 16px; margin-top: 12px; padding-top: 12px; border-top: 1px solid var(--border); }
+    .meta-item { display: flex; align-items: center; gap: 6px; font-size: 0.75rem; color: var(--text-muted); }
+    .badge { padding: 2px 8px; border-radius: 4px; font-size: 0.68rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; }
+    .badge-on { background: rgba(16,185,129,0.15); color: var(--green); }
+    .badge-off { background: rgba(107,114,128,0.15); color: #6b7280; }
+    .variants-chip { font-family: monospace; font-size: 0.72rem; background: var(--code-bg); padding: 2px 8px; border-radius: 4px; color: var(--text-muted); max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    /* Modal */
+    .modal-backdrop { position: fixed; inset: 0; background: rgba(0,0,0,0.7); backdrop-filter: blur(4px); z-index: 100; display: none; align-items: center; justify-content: center; }
+    .modal-backdrop.open { display: flex; }
+    .modal { background: var(--card-bg); border: 1px solid var(--border); border-radius: 12px; padding: 28px; width: 90%; max-width: 520px; }
+    .modal-title { font-size: 1.1rem; font-weight: 700; margin-bottom: 20px; }
+    .form-group { margin-bottom: 16px; }
+    .form-label { display: block; font-size: 0.78rem; font-weight: 600; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 6px; }
+    .form-input { width: 100%; padding: 9px 12px; background: var(--bg); border: 1px solid var(--border); border-radius: 6px; color: var(--text); font-size: 0.875rem; outline: none; transition: border-color 0.15s; }
+    .form-input:focus { border-color: var(--accent); }
+    .form-input.mono { font-family: monospace; }
+    .form-row { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+    .modal-actions { display: flex; justify-content: flex-end; gap: 10px; margin-top: 24px; }
+    .empty-state { text-align: center; padding: 64px 24px; color: var(--text-muted); }
+    .empty-icon { font-size: 2.5rem; margin-bottom: 12px; }
+    .empty-text { font-size: 0.9rem; margin-bottom: 16px; }
+    .toast { position: fixed; bottom: 24px; right: 24px; background: var(--card-bg); border: 1px solid var(--border); border-radius: 8px; padding: 12px 18px; font-size: 0.82rem; z-index: 200; transform: translateY(80px); opacity: 0; transition: all 0.25s; }
+    .toast.show { transform: translateY(0); opacity: 1; }
+    .toast.success { border-left: 3px solid var(--green); }
+    .toast.error { border-left: 3px solid var(--red); }
+    .rollout-bar { height: 4px; background: var(--border); border-radius: 2px; margin-top: 8px; overflow: hidden; }
+    .rollout-fill { height: 100%; background: var(--accent); border-radius: 2px; transition: width 0.3s; }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="brand">
+      <div class="brand-icon">\u{1F6A9}</div>
+      <div>
+        <div class="brand-name">nexus-flags-dev</div>
+        <div class="brand-sub">Local Feature Flag Management</div>
+      </div>
+    </div>
+    <div class="header-meta">
+      <div class="sse-counter" id="sseCount">0 connected clients</div>
+      <div class="status-badge"><div class="status-dot"></div>Live on :${port}</div>
+    </div>
+  </header>
+
+  <main>
+    <div class="page-header">
+      <div>
+        <div class="page-title">Feature <span>Flags</span></div>
+      </div>
+      <button class="btn btn-primary" onclick="openModal()">\uFF0B New Flag</button>
+    </div>
+
+    <div class="stats-bar">
+      <div class="stat-card">
+        <div class="stat-label">Total Flags</div>
+        <div class="stat-value" id="statTotal">0</div>
+      </div>
+      <div class="stat-card">
+        <div class="stat-label">Enabled</div>
+        <div class="stat-value green" id="statEnabled">0</div>
+      </div>
+      <div class="stat-card">
+        <div class="stat-label">SSE Clients</div>
+        <div class="stat-value" id="statClients">0</div>
+      </div>
+    </div>
+
+    <div class="flag-list" id="flagList">
+      <div class="empty-state">
+        <div class="empty-icon">\u{1F6A9}</div>
+        <div class="empty-text">Loading flags...</div>
+      </div>
+    </div>
+  </main>
+
+  <!-- Create / Edit Modal -->
+  <div class="modal-backdrop" id="modal">
+    <div class="modal">
+      <div class="modal-title" id="modalTitle">Create Flag</div>
+      <div class="form-group">
+        <label class="form-label">Flag Key <span style="color:#ef4444">*</span></label>
+        <input class="form-input mono" id="fieldKey" placeholder="new_checkout (snake_case)" />
+      </div>
+      <div class="form-group">
+        <label class="form-label">Display Name</label>
+        <input class="form-input" id="fieldName" placeholder="New Checkout Flow" />
+      </div>
+      <div class="form-group">
+        <label class="form-label">Description</label>
+        <input class="form-input" id="fieldDesc" placeholder="Short description of this flag" />
+      </div>
+      <div class="form-row">
+        <div class="form-group">
+          <label class="form-label">Rollout %</label>
+          <input class="form-input" id="fieldRollout" type="number" min="0" max="100" value="100" />
+        </div>
+        <div class="form-group">
+          <label class="form-label">Enabled</label>
+          <select class="form-input" id="fieldEnabled">
+            <option value="false">Disabled</option>
+            <option value="true">Enabled</option>
+          </select>
+        </div>
+      </div>
+      <div class="form-group">
+        <label class="form-label">Variants (JSON object)</label>
+        <input class="form-input mono" id="fieldVariants" placeholder='{"theme": "dark", "discount": 10}' />
+      </div>
+      <div class="modal-actions">
+        <button class="btn btn-ghost" onclick="closeModal()">Cancel</button>
+        <button class="btn btn-primary" onclick="submitFlag()" id="submitBtn">Create Flag</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="toast" id="toast"></div>
+
+  <script>
+    const API = '';
+    let flags = [];
+    let editingKey = null;
+
+    async function loadFlags() {
+      try {
+        const res = await fetch(API + '/api/v1/flags');
+        const data = await res.json();
+        flags = data.flags || [];
+        renderFlags();
+        updateStats();
+      } catch (e) { showToast('Failed to load flags', 'error'); }
+    }
+
+    function renderFlags() {
+      const list = document.getElementById('flagList');
+      if (!flags.length) {
+        list.innerHTML = '<div class="empty-state"><div class="empty-icon">\u{1F6A9}</div><div class="empty-text">No flags yet. Create your first flag!</div></div>';
+        return;
+      }
+      list.innerHTML = flags.map(f => {
+        const variantStr = Object.keys(f.variants || {}).length > 0
+          ? JSON.stringify(f.variants).substring(0, 60) + (JSON.stringify(f.variants).length > 60 ? '...' : '')
+          : 'no variants';
+        return \`
+          <div class="flag-card \${f.enabled ? 'enabled' : 'disabled'}" id="card-\${f.key}">
+            <div class="flag-top">
+              <div class="flag-info">
+                <div class="flag-key">\${f.key}</div>
+                <div class="flag-name">\${f.name}</div>
+                \${f.description ? \`<div class="flag-desc">\${f.description}</div>\` : ''}
+              </div>
+              <div class="flag-actions">
+                <label class="toggle" title="\${f.enabled ? 'Disable' : 'Enable'} flag">
+                  <input type="checkbox" \${f.enabled ? 'checked' : ''} onchange="toggleFlag('\${f.key}', this.checked)">
+                  <span class="toggle-slider"></span>
+                </label>
+                <button class="btn btn-ghost btn-sm" onclick="openEditModal('\${f.key}')">Edit</button>
+                <button class="btn btn-danger btn-sm" onclick="deleteFlag('\${f.key}')">Delete</button>
+              </div>
+            </div>
+            <div class="flag-meta">
+              <span class="badge \${f.enabled ? 'badge-on' : 'badge-off'}">\${f.enabled ? 'enabled' : 'disabled'}</span>
+              <span class="meta-item">Rollout: \${f.rolloutPercentage}%</span>
+              <span class="variants-chip">\${variantStr}</span>
+              <span class="meta-item" style="margin-left:auto;font-size:0.68rem;">\${new Date(f.updatedAt).toLocaleString()}</span>
+            </div>
+            <div class="rollout-bar"><div class="rollout-fill" style="width:\${f.rolloutPercentage}%"></div></div>
+          </div>
+        \`;
+      }).join('');
+    }
+
+    function updateStats() {
+      document.getElementById('statTotal').textContent = flags.length;
+      document.getElementById('statEnabled').textContent = flags.filter(f => f.enabled).length;
+    }
+
+    async function toggleFlag(key, enabled) {
+      try {
+        await fetch(API + '/api/v1/flags/' + key + '/toggle', { method: 'POST' });
+        await loadFlags();
+        showToast(enabled ? \`"\${key}" enabled \u2014 all connected clients updated!\` : \`"\${key}" disabled\`, 'success');
+      } catch { showToast('Toggle failed', 'error'); }
+    }
+
+    async function deleteFlag(key) {
+      if (!confirm(\`Delete flag "\${key}"? This cannot be undone.\`)) return;
+      try {
+        await fetch(API + '/api/v1/flags/' + key, { method: 'DELETE' });
+        await loadFlags();
+        showToast(\`Flag "\${key}" deleted\`, 'success');
+      } catch { showToast('Delete failed', 'error'); }
+    }
+
+    function openModal() {
+      editingKey = null;
+      document.getElementById('modalTitle').textContent = 'Create Flag';
+      document.getElementById('submitBtn').textContent = 'Create Flag';
+      document.getElementById('fieldKey').disabled = false;
+      ['fieldKey','fieldName','fieldDesc','fieldVariants'].forEach(id => document.getElementById(id).value = '');
+      document.getElementById('fieldRollout').value = '100';
+      document.getElementById('fieldEnabled').value = 'false';
+      document.getElementById('modal').classList.add('open');
+      setTimeout(() => document.getElementById('fieldKey').focus(), 100);
+    }
+
+    function openEditModal(key) {
+      const flag = flags.find(f => f.key === key);
+      if (!flag) return;
+      editingKey = key;
+      document.getElementById('modalTitle').textContent = 'Edit Flag';
+      document.getElementById('submitBtn').textContent = 'Save Changes';
+      document.getElementById('fieldKey').value = key;
+      document.getElementById('fieldKey').disabled = true;
+      document.getElementById('fieldName').value = flag.name || '';
+      document.getElementById('fieldDesc').value = flag.description || '';
+      document.getElementById('fieldRollout').value = String(flag.rolloutPercentage ?? 100);
+      document.getElementById('fieldEnabled').value = String(flag.enabled);
+      document.getElementById('fieldVariants').value = Object.keys(flag.variants || {}).length ? JSON.stringify(flag.variants) : '';
+      document.getElementById('modal').classList.add('open');
+    }
+
+    function closeModal() { document.getElementById('modal').classList.remove('open'); }
+
+    async function submitFlag() {
+      const key = document.getElementById('fieldKey').value.trim();
+      const name = document.getElementById('fieldName').value.trim() || key;
+      const description = document.getElementById('fieldDesc').value.trim();
+      const rolloutPercentage = parseInt(document.getElementById('fieldRollout').value, 10) || 100;
+      const enabled = document.getElementById('fieldEnabled').value === 'true';
+      const variantsRaw = document.getElementById('fieldVariants').value.trim();
+      let variants = {};
+      if (variantsRaw) {
+        try { variants = JSON.parse(variantsRaw); } catch { showToast('Variants must be valid JSON', 'error'); return; }
+      }
+      if (!key) { showToast('Flag key is required', 'error'); return; }
+      const body = { key, name, description, rolloutPercentage, enabled, variants };
+      try {
+        if (editingKey) {
+          await fetch(API + '/api/v1/flags/' + editingKey, { method: 'PATCH', headers: {'Content-Type':'application/json'}, body: JSON.stringify(body) });
+        } else {
+          await fetch(API + '/api/v1/flags', { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify(body) });
+        }
+        closeModal();
+        await loadFlags();
+        showToast(editingKey ? 'Flag updated' : \`Flag "\${key}" created\`, 'success');
+      } catch { showToast('Save failed', 'error'); }
+    }
+
+    function showToast(msg, type = 'success') {
+      const t = document.getElementById('toast');
+      t.textContent = msg;
+      t.className = 'toast ' + type + ' show';
+      setTimeout(() => { t.className = 'toast ' + type; }, 2800);
+    }
+
+    // SSE \u2014 realtime flag sync display
+    const evtSrc = new EventSource(API + '/api/v1/flags/stream');
+    evtSrc.addEventListener('FLAG_UPDATE', () => loadFlags());
+    evtSrc.addEventListener('FLAG_DELETE', () => loadFlags());
+
+    // Poll stats
+    async function pollStats() {
+      try {
+        const r = await fetch(API + '/health');
+        const d = await r.json();
+        const c = d.connectedClients || 0;
+        document.getElementById('statClients').textContent = c;
+        document.getElementById('sseCount').textContent = c + ' connected client' + (c === 1 ? '' : 's');
+      } catch {}
+    }
+    setInterval(pollStats, 5000);
+
+    // Close modal on backdrop click
+    document.getElementById('modal').addEventListener('click', e => { if (e.target === e.currentTarget) closeModal(); });
+
+    loadFlags();
+    pollStats();
+  </script>
+</body>
+</html>`;
+}
+
+// src/dev-server/server.ts
+function setCors(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Nexus-API-Key");
+  res.setHeader("Access-Control-Max-Age", "86400");
+}
+function json(res, status, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Content-Length": Buffer.byteLength(body) });
+  res.end(body);
+}
+function html(res, body) {
+  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Content-Length": Buffer.byteLength(body) });
+  res.end(body);
+}
+function problem(res, status, title, detail) {
+  json(res, status, { type: `https://nexus.dev/problems/${title.toLowerCase().replace(/ /g, "-")}`, title, status, detail });
+}
+function parseBody(req) {
+  return new Promise((resolve2, reject) => {
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > 1048576) {
+        req.destroy();
+        reject(new Error("Payload too large"));
+      }
+    });
+    req.on("end", () => {
+      try {
+        resolve2(raw.trim() ? JSON.parse(raw) : {});
+      } catch {
+        reject(new Error("Invalid JSON"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function startFlagsDevServer(options = {}) {
+  const port = options.port ?? 4568;
+  const host = options.host ?? "localhost";
+  const flagsFile = options.flagsFile ?? "./nexus-flags.json";
+  const store = new DevFlagStore(flagsFile);
+  const sse = new FlagSseBroadcaster();
+  if (options.seed !== false) store.seedIfEmpty();
+  return new Promise((resolve2, reject) => {
+    const server = createServer(async (req, res) => {
+      setCors(res);
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", `http://${host}:${port}`);
+      const p = url.pathname;
+      const method = req.method ?? "GET";
+      if (method === "GET" && p === "/health") {
+        json(res, 200, { status: "ok", uptime: process.uptime(), flagCount: store.size(), connectedClients: sse.clientCount });
+        return;
+      }
+      if (method === "GET" && (p === "/" || p === "/gui")) {
+        html(res, renderFlagsGuiHtml(port));
+        return;
+      }
+      if (method === "GET" && (p === "/api/v1/flags/stream" || p === "/flags/stream")) {
+        sse.addClient(res);
+        return;
+      }
+      if (method === "GET" && (p === "/api/v1/flags/bootstrap" || p === "/flags/bootstrap")) {
+        json(res, 200, store.getBootstrapSnapshot());
+        return;
+      }
+      if (method === "GET" && (p === "/api/v1/flags/eval" || p === "/flags/eval")) {
+        const snapshot = {};
+        for (const flag of store.getAll()) {
+          snapshot[flag.key] = {
+            id: flag.key,
+            projectId: "dev-project",
+            environment: "development",
+            key: flag.key,
+            name: flag.name,
+            description: flag.description,
+            isEnabled: flag.enabled,
+            rolloutPercentage: flag.rolloutPercentage,
+            targetingRules: [],
+            variants: flag.variants,
+            version: 1,
+            createdAt: flag.createdAt,
+            updatedAt: flag.updatedAt
+          };
+        }
+        json(res, 200, snapshot);
+        return;
+      }
+      if (method === "GET" && p === "/api/v1/flags") {
+        json(res, 200, { flags: store.getAll(), total: store.size() });
+        return;
+      }
+      if (method === "POST" && p === "/api/v1/flags") {
+        try {
+          const body = await parseBody(req);
+          const key = String(body.key ?? "").trim();
+          if (!key) {
+            problem(res, 400, "Bad Request", '"key" is required.');
+            return;
+          }
+          const flag = store.create({
+            key,
+            name: body.name ? String(body.name) : void 0,
+            description: body.description ? String(body.description) : void 0,
+            enabled: Boolean(body.enabled ?? false),
+            rolloutPercentage: typeof body.rolloutPercentage === "number" ? body.rolloutPercentage : 100,
+            variants: body.variants && typeof body.variants === "object" ? body.variants : {}
+          });
+          sse.broadcastFlagUpdate(flag.key, flag.enabled, flag.variants);
+          json(res, 201, { flag });
+        } catch (err) {
+          problem(res, 409, "Conflict", err instanceof Error ? err.message : "Unknown error");
+        }
+        return;
+      }
+      const flagKeyMatch = p.match(/^\/api\/v1\/flags\/([^/]+)$/);
+      if (method === "GET" && flagKeyMatch) {
+        const key = decodeURIComponent(flagKeyMatch[1] ?? "");
+        const flag = store.getByKey(key);
+        if (!flag) {
+          problem(res, 404, "Not Found", `Flag "${key}" does not exist.`);
+          return;
+        }
+        json(res, 200, { flag });
+        return;
+      }
+      if (method === "PATCH" && flagKeyMatch) {
+        const key = decodeURIComponent(flagKeyMatch[1] ?? "");
+        try {
+          const body = await parseBody(req);
+          const flag = store.update(key, {
+            name: body.name ? String(body.name) : void 0,
+            description: body.description !== void 0 ? String(body.description) : void 0,
+            enabled: body.enabled !== void 0 ? Boolean(body.enabled) : void 0,
+            rolloutPercentage: typeof body.rolloutPercentage === "number" ? body.rolloutPercentage : void 0,
+            variants: body.variants && typeof body.variants === "object" ? body.variants : void 0
+          });
+          sse.broadcastFlagUpdate(flag.key, flag.enabled, flag.variants);
+          json(res, 200, { flag });
+        } catch (err) {
+          problem(res, 404, "Not Found", err instanceof Error ? err.message : "Not found");
+        }
+        return;
+      }
+      if (method === "DELETE" && flagKeyMatch) {
+        const key = decodeURIComponent(flagKeyMatch[1] ?? "");
+        const deleted = store.delete(key);
+        if (!deleted) {
+          problem(res, 404, "Not Found", `Flag "${key}" does not exist.`);
+          return;
+        }
+        sse.broadcastFlagDelete(key);
+        json(res, 200, { success: true, key });
+        return;
+      }
+      const toggleMatch = p.match(/^\/api\/v1\/flags\/([^/]+)\/toggle$/);
+      if (method === "POST" && toggleMatch) {
+        const key = decodeURIComponent(toggleMatch[1] ?? "");
+        try {
+          const flag = store.toggle(key);
+          sse.broadcastFlagUpdate(flag.key, flag.enabled, flag.variants);
+          json(res, 200, { flag });
+        } catch (err) {
+          problem(res, 404, "Not Found", err instanceof Error ? err.message : "Not found");
+        }
+        return;
+      }
+      problem(res, 404, "Not Found", `No handler for ${method} ${p}`);
+    });
+    server.on("error", (err) => reject(err));
+    server.listen(port, host, () => {
+      const instance = {
+        server,
+        port,
+        host,
+        store,
+        sse,
+        close: () => new Promise((done) => {
+          sse.destroy();
+          server.close(() => done());
+        })
+      };
+      resolve2(instance);
+    });
+  });
+}
+
+export {
+  DevFlagStore,
+  FlagSseBroadcaster,
+  startFlagsDevServer
+};