@sanjay5114/cdx 1.0.0

package/lib/ai.js

@@ -0,0 +1,249 @@
+"use strict";
+
+const fetch = require("./fetch");
+
+const MODELS = [
+  "gemini-2.5-pro-preview-03-25",
+  "gemini-2.0-flash",
+  "gemini-1.5-pro",
+  "gemini-1.5-flash",
+];
+
+function geminiUrl(model) {
+  return `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+async function geminiRaw(apiKey, model, prompt, maxTokens = 8192) {
+  const res = await fetch(geminiUrl(model), {
+    method : "POST",
+    headers: { "Content-Type": "application/json", "x-goog-api-key": apiKey },
+    body   : JSON.stringify({
+      contents       : [{ parts: [{ text: prompt }] }],
+      generationConfig: { temperature: 0.4, maxOutputTokens: maxTokens, topP: 0.95 },
+    }),
+    signal: AbortSignal.timeout(90_000),
+  });
+
+  if (res.status === 429) { const e = new Error("RATE_LIMIT"); e.isRateLimit = true; throw e; }
+  if (res.status === 503) { const e = new Error("SERVICE_UNAVAILABLE"); e.isRetryable = true; throw e; }
+  if (!res.ok) {
+    const txt = await res.text().catch(() => "");
+    throw new Error(`HTTP ${res.status}: ${txt.slice(0, 200)}`);
+  }
+  const data = await res.json();
+  const text = data?.candidates?.[0]?.content?.parts?.[0]?.text;
+  if (!text) {
+    const reason = data?.candidates?.[0]?.finishReason;
+    if (reason === "SAFETY") throw new Error("Response blocked by safety filters.");
+    throw new Error("Empty response from model.");
+  }
+  return text;
+}
+
+async function geminiCall(apiKey, prompt, opts = {}) {
+  const { maxTokens = 8192, maxRetries = 6, baseDelay = 3000, onProgress, modelIndex = 0 } = opts;
+  const report = (msg) => { if (onProgress) onProgress(msg); else process.stdout.write(`\r   ${msg}                    `); };
+  const model = MODELS[Math.min(modelIndex, MODELS.length - 1)];
+  let lastErr;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await geminiRaw(apiKey, model, prompt, maxTokens);
+    } catch (e) {
+      lastErr = e;
+      if (e.isRateLimit || e.isRetryable) {
+        const waitMs   = Math.min(baseDelay * Math.pow(2, attempt) + Math.floor(Math.random() * 1500), 60_000);
+        const waitSecs = Math.ceil(waitMs / 1000);
+        for (let s = waitSecs; s > 0; s--) {
+          report(`Rate-limited on ${model}. Retrying in ${s}s… (attempt ${attempt + 1}/${maxRetries})`);
+          await sleep(1000);
+        }
+        if (!onProgress) process.stdout.write("\n");
+      } else {
+        if (modelIndex < MODELS.length - 1) {
+          report(`Model ${model} failed. Cascading to next model…`);
+          await sleep(1500);
+          return geminiCall(apiKey, prompt, { ...opts, modelIndex: modelIndex + 1, maxRetries: 3 });
+        }
+        if (attempt > 0) await sleep(2000);
+      }
+    }
+  }
+  const err = new Error(`AI generation failed: ${lastErr?.message}`);
+  err.code = lastErr?.isRateLimit ? "RATE_LIMIT_EXCEEDED" : "AI_ERROR";
+  throw err;
+}
+
+function extractJson(raw) {
+  try { return JSON.parse(raw); } catch {}
+  const stripped = raw.replace(/```(?:json)?\n?/g, "").trim();
+  try { return JSON.parse(stripped); } catch {}
+  const m = stripped.match(/(\[[\s\S]*\]|\{[\s\S]*\})/);
+  if (m) { try { return JSON.parse(m[1]); } catch {} }
+  return null;
+}
+
+async function pass1FileSummaries(apiKey, metas, opts = {}) {
+  const BATCH = 8;
+  const summaries = [];
+  for (let i = 0; i < metas.length; i += BATCH) {
+    const batch = metas.slice(i, i + BATCH);
+    opts.onProgress && opts.onProgress(`Pass 1 — Analyzing files ${i + 1}–${Math.min(i + BATCH, metas.length)} of ${metas.length}…`);
+    const prompt = `You are a senior software architect conducting a rigorous code review.
+Analyze the file metadata and provide a precise technical summary for each file.
+
+REQUIREMENTS:
+- Each summary: 1-2 sentences, highly specific (mention what the module DOES, not that it "exists")
+- Use engineering terminology (e.g., "implements OAuth 2.0 PKCE flow", "exposes REST endpoints")
+- Identify architectural role: controller, service, utility, middleware, model, gateway, config, etc.
+- Do NOT use generic phrases like "handles logic" or "manages stuff"
+
+Return ONLY a valid JSON array, no markdown, no preamble:
+[{ "file": "path", "role": "architectural role", "summary": "precise description" }]
+
+FILE METADATA:
+${JSON.stringify(batch, null, 2)}`;
+    try {
+      const raw    = await geminiCall(apiKey, prompt, { maxTokens: 2048, ...opts });
+      const parsed = extractJson(raw);
+      if (Array.isArray(parsed)) summaries.push(...parsed);
+      else for (const m of batch) summaries.push({ file: m.file, role: "module", summary: `${m.ext} module — ${m.functions} functions, complexity score ${m.complexity}.` });
+      opts.onProgress && opts.onProgress(`Pass 1 — Completed ${Math.min(i + BATCH, metas.length)}/${metas.length}`);
+    } catch (e) { throw e; }
+  }
+  return summaries;
+}
+
+async function pass2SystemOverview(apiKey, metas, summaries, stackInfo, opts = {}) {
+  opts.onProgress && opts.onProgress("Pass 2 — Synthesizing system architecture overview…");
+  const prompt = `You are a Principal Engineer authoring formal internal architecture documentation for a ${stackInfo.stack} project.
+
+Using the file metadata and module summaries below, produce a comprehensive SYSTEM OVERVIEW of 600–900 words.
+
+Use these exact subheadings:
+## Executive Summary
+## Architectural Pattern
+## Core Subsystems
+## Data Flow & Integration Points
+## Technology Stack
+## Dependency Topology
+## Quality & Risk Profile
+
+STYLE: Precise corporate engineering language. Reference real file paths. No hedging. Declarative prose only.
+
+STACK CONTEXT: ${stackInfo.stack} | ${stackInfo.reasons.join("; ")}
+TOTAL FILES: ${metas.length}
+
+FILE SUMMARIES:
+${JSON.stringify(summaries, null, 2)}
+
+FULL METADATA:
+${JSON.stringify(metas, null, 2)}`;
+  return geminiCall(apiKey, prompt, { maxTokens: 4096, ...opts });
+}
+
+async function pass3FullDocs(apiKey, overview, summaries, metas, stackInfo, opts = {}) {
+  opts.onProgress && opts.onProgress("Pass 3 — Generating comprehensive documentation suite…");
+  const prompt = `You are a Staff Technical Writer at a Tier-1 software engineering organization producing the definitive documentation suite for this codebase.
+
+Generate ALL sections with MAXIMUM DETAIL and CORPORATE-GRADE QUALITY.
+
+Use THESE EXACT HEADING MARKERS:
+# README.md
+# Architecture
+# Onboarding
+# Usage
+# Security
+# API Reference
+# Contributing
+# Changelog
+
+SECTION SPECIFICATIONS:
+
+# README.md (400-600 words)
+- Project name, tagline, concise description
+- Badges (build, version, license — placeholder URLs)
+- Table of Contents (linked)
+- Features section (8-12 specific concrete features)
+- Prerequisites (exact versions where inferable)
+- Quick Start (numbered commands)
+- Project Structure (tree view with descriptions)
+- Configuration reference table (key | type | default | description)
+- Links to other doc sections
+
+# Architecture (500-700 words)
+- Overview paragraph
+- ASCII diagram showing module relationships
+- Subsystem breakdown with responsibilities
+- Design decisions and trade-offs
+- Primary user flow as ASCII sequence diagram
+- Technology decisions rationale
+
+# Onboarding
+- Environment setup (step-by-step, exact commands)
+- Environment variables table (variable | required | default | description)
+- Development workflow
+- Running tests
+- Common pitfalls and solutions (at least 5 items)
+
+# Usage
+- CLI reference table (command | flags | description | example)
+- Detailed examples for all major use cases with realistic output
+- Advanced configuration scenarios
+
+# Security
+- Authentication & authorization model
+- Secrets management policy (exact file locations, permissions)
+- Data classification table
+- Threat model (4+ specific threats with mitigations)
+- Vulnerability disclosure process
+
+# API Reference
+- Infer from file structure: endpoints, request/response schemas, error codes
+
+# Contributing
+- Contribution workflow (fork, branch naming, PR template)
+- Coding standards and linting
+- Review checklist (10+ items)
+
+# Changelog
+- [Unreleased] section with inferred features
+- v1.0.0 initial release stub
+
+CRITICAL RULES:
+1. Reference REAL file paths from metadata — never invent filenames
+2. Every section MUST be substantive — no one-liners or thin bullets
+3. Tables must be proper markdown with | alignment
+4. ASCII diagrams must be architecturally accurate
+5. Do NOT use placeholder text like "[Add here]"
+6. Omit rather than fabricate if something cannot be inferred
+
+CONTEXT: Stack: ${stackInfo.stack} | Total files: ${metas.length}
+
+SYSTEM OVERVIEW:
+${overview}
+
+FILE SUMMARIES:
+${JSON.stringify(summaries, null, 2)}
+
+FILE METADATA:
+${JSON.stringify(metas, null, 2)}`;
+  return geminiCall(apiKey, prompt, { maxTokens: 8192, ...opts });
+}
+
+async function pass4Improve(apiKey, existingDoc, instruction, opts = {}) {
+  opts.onProgress && opts.onProgress(`Applying: "${instruction.slice(0, 60)}…"`);
+  const prompt = `You are a senior technical writer improving an existing documentation set.
+
+INSTRUCTION: "${instruction}"
+
+Apply this instruction to the documentation below. Return the COMPLETE updated documentation — do not truncate or omit existing sections unless the instruction explicitly removes them. Maintain all heading markers.
+
+EXISTING DOCUMENTATION:
+${existingDoc}`;
+  return geminiCall(apiKey, prompt, { maxTokens: 8192, ...opts });
+}
+
+module.exports = { geminiCall, pass1FileSummaries, pass2SystemOverview, pass3FullDocs, pass4Improve, extractJson, MODELS };

package/lib/auth.js

@@ -0,0 +1,120 @@
+"use strict";
+
+/**
+ * CDX Firebase Authentication
+ * Handles sign-up, sign-in, token refresh, and secure local JWT persistence.
+ * Uses the Firebase Auth REST API (no native SDK required).
+ */
+
+const fetch = require("./fetch");
+const store = require("./store");
+
+const FB_BASE    = "https://identitytoolkit.googleapis.com/v1/accounts";
+const REFRESH_URL = "https://securetoken.googleapis.com/v1/token";
+
+function fbUrl(action, apiKey) { return `${FB_BASE}:${action}?key=${apiKey}`; }
+
+async function fbPost(url, body) {
+  const res  = await fetch(url, {
+    method : "POST",
+    headers: { "Content-Type": "application/json" },
+    body   : JSON.stringify(body),
+    signal : AbortSignal.timeout(15_000),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    const msg = data?.error?.message || `HTTP ${res.status}`;
+    const e   = new Error(humanizeFirebaseError(msg));
+    e.code    = msg;
+    throw e;
+  }
+  return data;
+}
+
+function humanizeFirebaseError(code) {
+  const MAP = {
+    "EMAIL_EXISTS"               : "An account with this email address already exists.",
+    "INVALID_EMAIL"              : "The email address is not valid.",
+    "WEAK_PASSWORD"              : "Password must be at least 6 characters.",
+    "EMAIL_NOT_FOUND"            : "No account found with this email address.",
+    "INVALID_PASSWORD"           : "Incorrect password. Please try again.",
+    "USER_DISABLED"              : "This account has been disabled.",
+    "TOO_MANY_ATTEMPTS_TRY_LATER": "Too many failed attempts. Please try again later.",
+    "INVALID_LOGIN_CREDENTIALS"  : "Invalid email or password.",
+    "TOKEN_EXPIRED"              : "Your session has expired. Please sign in again.",
+    "USER_NOT_FOUND"             : "No user found with these credentials.",
+    "OPERATION_NOT_ALLOWED"      : "Email/password sign-in is not enabled for this project.",
+    "MISSING_PASSWORD"           : "Password is required.",
+  };
+  for (const [k, v] of Object.entries(MAP)) { if (code.includes(k)) return v; }
+  return `Authentication error: ${code}`;
+}
+
+async function signUp(apiKey, email, password, displayName = "") {
+  const data = await fbPost(fbUrl("signUp", apiKey), { email, password, returnSecureToken: true });
+  if (displayName && data.idToken) {
+    await fbPost(fbUrl("update", apiKey), { idToken: data.idToken, displayName, returnSecureToken: false }).catch(() => {});
+  }
+  return { uid: data.localId, email: data.email, displayName: displayName || data.email.split("@")[0], idToken: data.idToken, refreshToken: data.refreshToken, expiresIn: data.expiresIn };
+}
+
+async function signIn(apiKey, email, password) {
+  const data = await fbPost(fbUrl("signInWithPassword", apiKey), { email, password, returnSecureToken: true });
+  return { uid: data.localId, email: data.email, displayName: data.displayName || data.email.split("@")[0], idToken: data.idToken, refreshToken: data.refreshToken, expiresIn: data.expiresIn };
+}
+
+async function doRefreshToken(apiKey, rToken) {
+  const res  = await fetch(`${REFRESH_URL}?key=${apiKey}`, {
+    method : "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body   : `grant_type=refresh_token&refresh_token=${encodeURIComponent(rToken)}`,
+    signal : AbortSignal.timeout(15_000),
+  });
+  const data = await res.json();
+  if (!res.ok) throw new Error(humanizeFirebaseError(data?.error?.message || `HTTP ${res.status}`));
+  return { idToken: data.id_token, refreshToken: data.refresh_token, expiresIn: data.expires_in };
+}
+
+async function sendPasswordReset(apiKey, email) {
+  await fbPost(fbUrl("sendOobCode", apiKey), { requestType: "PASSWORD_RESET", email });
+}
+
+function persistSession(session) {
+  store.saveSession(session.idToken);
+  store.set("refreshToken",  session.refreshToken);
+  store.set("userEmail",     session.email);
+  store.set("userName",      session.displayName || "");
+  store.set("userUid",       session.uid || "");
+}
+
+async function restoreSession() {
+  const apiKey     = store.get("firebaseApiKey");
+  const idToken    = store.loadSession();
+  const refreshTok = store.get("refreshToken");
+  const email      = store.get("userEmail");
+  if (!apiKey || !email) return null;
+  if (idToken && store.sessionIsAlive(idToken)) {
+    const d = store.decodeJwt(idToken);
+    return { uid: d?.user_id || d?.sub || "", email: d?.email || email, displayName: store.get("userName") || email.split("@")[0], idToken };
+  }
+  if (refreshTok) {
+    try {
+      const r = await doRefreshToken(apiKey, refreshTok);
+      store.saveSession(r.idToken);
+      store.set("refreshToken", r.refreshToken);
+      const d = store.decodeJwt(r.idToken);
+      return { uid: d?.user_id || d?.sub || "", email: d?.email || email, displayName: store.get("userName") || email.split("@")[0], idToken: r.idToken };
+    } catch {}
+  }
+  return null;
+}
+
+function signOut() {
+  store.clearSession();
+  store.del("refreshToken");
+  store.del("userEmail");
+  store.del("userName");
+  store.del("userUid");
+}
+
+module.exports = { signUp, signIn, doRefreshToken, sendPasswordReset, persistSession, restoreSession, signOut };

package/lib/fetch.js

@@ -0,0 +1,46 @@
+"use strict";
+
+/**
+ * Universal fetch helper.
+ * Node 18+ ships native `fetch` globally — use it.
+ * Older Node: dynamically import node-fetch v2 (CJS-compatible).
+ * This avoids the ERR_REQUIRE_ESM crash from node-fetch v3.
+ */
+
+let _fetchFn = null;
+
+async function getFetch() {
+  if (_fetchFn) return _fetchFn;
+
+  // Node 18+ has globalThis.fetch natively
+  if (typeof globalThis.fetch === "function") {
+    _fetchFn = globalThis.fetch.bind(globalThis);
+    return _fetchFn;
+  }
+
+  // Fallback: node-fetch v2 (CommonJS)
+  try {
+    _fetchFn = require("node-fetch");
+    return _fetchFn;
+  } catch {}
+
+  // Last resort: dynamic import (works with node-fetch v2 or v3)
+  try {
+    const mod = await import("node-fetch");
+    _fetchFn = mod.default || mod;
+    return _fetchFn;
+  } catch (e) {
+    throw new Error("No fetch implementation available. Run: npm install node-fetch@2");
+  }
+}
+
+/**
+ * Drop-in async fetch wrapper.
+ * Usage: const res = await fetch(url, options);
+ */
+async function fetch(url, options) {
+  const fn = await getFetch();
+  return fn(url, options);
+}
+
+module.exports = fetch;