@sanjay5114/cdx 1.0.0

package/commands/create.js

@@ -0,0 +1,474 @@
+"use strict";
+
+/**
+ * CDX Create Command
+ * Full pipeline: scan → detect stack → AI passes → write → push → interactive improvement loop
+ */
+
+const fs      = require("fs").promises;
+const path    = require("path");
+const chalk   = require("chalk");
+
+const { T, section, ok, warn, err, info, note, spinner, progressBar, table, badge, panel, ICONS, footer, rule, center, W } = require("../lib/ui");
+const { runLocalPipeline, runRemotePipeline, pushToGitHub, extractSection } = require("../lib/scanner");
+const { pass1FileSummaries, pass2SystemOverview, pass3FullDocs, pass4Improve } = require("../lib/ai");
+const store = require("../lib/store");
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+// ─── Local fallback (no Gemini key) ──────────────────────────────────────────
+function generateLocalDocs(metas, stackInfo) {
+  const topFiles  = metas.slice(0, 15);
+  const byExt     = {};
+  for (const m of metas) byExt[m.ext] = (byExt[m.ext] || 0) + 1;
+  const langs     = Object.entries(byExt).sort((a,b)=>b[1]-a[1]).map(([e])=>e || "misc").join(", ");
+  const totalFns  = metas.reduce((s,m) => s + m.functions, 0);
+  const totalImps = metas.reduce((s,m) => s + m.imports,   0);
+
+  const tree = topFiles.map(m =>
+    `├── ${m.file}${" ".repeat(Math.max(1, 50 - m.file.length))}# ${m.functions} fn · ${m.complexity} branches`
+  ).join("\n");
+
+  return `# README.md
+
+## Project Overview
+
+A ${stackInfo.stack} software project comprising **${metas.length} source files** across ${langs}.
+Analyzed ${totalFns} functions and ${totalImps} import declarations.
+Documentation generated locally via CDX — configure a Gemini API key for AI-enhanced output.
+
+## Features
+
+- Command-driven architecture with modular command handlers
+- Automated static metadata analysis across ${metas.length} source files
+- Stack-aware file prioritization (detected: ${stackInfo.stack})
+- Local documentation generation (no API required)
+- GitHub repository integration for remote analysis and push
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- npm >= 9.0.0
+
+## Quick Start
+
+\`\`\`bash
+git clone <repository-url>
+cd <project>
+npm install
+cdx config       # configure credentials
+cdx create README.md
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+${tree}
+\`\`\`
+
+## Configuration
+
+| Key              | Required | Default    | Description                       |
+|------------------|----------|------------|-----------------------------------|
+| geminiApiKey     | No       | —          | Gemini API key for AI-enhanced docs |
+| githubToken      | No       | —          | GitHub PAT for remote repos       |
+| githubRepo       | No       | —          | Target repo (owner/repo)          |
+| firebaseApiKey   | No       | —          | Firebase Web API key for auth     |
+
+# Architecture
+
+## Overview
+
+This project follows a ${stackInfo.stack === "node" || stackInfo.stack === "next" ? "layered command-driven" : "modular"} architecture.
+File analysis indicates ${metas.filter(m=>m.exports>0).length} modules with public exports and
+${metas.filter(m=>m.complexity>10).length} high-complexity files warranting attention.
+
+## Module Breakdown
+
+${topFiles.map(m => `### \`${m.file}\`\n- **Role**: ${m.exports > 0 ? "Exportable module" : "Internal module"}\n- **Complexity**: ${m.complexity} branching statements\n- **Functions**: ${m.functions}\n- **Imports**: ${m.imports} dependencies\n`).join("\n")}
+
+# Onboarding
+
+## Environment Setup
+
+1. **Clone the repository**
+   \`\`\`bash
+   git clone <repository-url> && cd <project>
+   \`\`\`
+
+2. **Install dependencies**
+   \`\`\`bash
+   npm install
+   \`\`\`
+
+3. **Configure CDX**
+   \`\`\`bash
+   cdx config
+   \`\`\`
+
+4. **Authenticate** (optional, requires Firebase API key)
+   \`\`\`bash
+   cdx auth login
+   \`\`\`
+
+5. **Generate documentation**
+   \`\`\`bash
+   cdx create README.md
+   \`\`\`
+
+## Common Pitfalls
+
+- Ensure Node.js >= 18 (uses native \`AbortSignal.timeout\`)
+- GitHub token requires \`repo\` scope for push operations
+- Gemini API key must have Generative Language API enabled
+- \`.env\` files are intentionally excluded from AI payloads for security
+- Large repositories (1500+ files) may require additional processing time
+
+# Usage
+
+## CLI Reference
+
+| Command                    | Description                              |
+|----------------------------|------------------------------------------|
+| \`cdx create <file>\`        | Generate documentation for current dir  |
+| \`cdx create <file> --all\`  | Include hidden files                     |
+| \`cdx config\`               | Interactive configuration manager        |
+| \`cdx auth login\`           | Sign in with email/password              |
+| \`cdx auth signup\`          | Create a new account                     |
+| \`cdx auth whoami\`          | Display current session info             |
+| \`cdx auth logout\`          | Sign out and clear session               |
+| \`cdx start\`                | Launch interactive terminal UI           |
+
+# Security
+
+## Secrets Management
+
+- All credentials stored in \`~/.cdx/config.json\` with \`0o600\` permissions (owner read/write only)
+- JWT session token stored separately in \`~/.cdx/.session\` with \`0o600\` permissions
+- Sensitive files (\`.env\`, \`*.pem\`, \`*.key\`, private keys) are explicitly excluded from AI payloads
+- GitHub tokens are never transmitted to the Gemini API
+- Firebase ID tokens are decoded locally — signature verification is handled server-side
+
+## Threat Mitigations
+
+| Threat                      | Mitigation                                              |
+|-----------------------------|---------------------------------------------------------|
+| Credential theft via config | 0o600 file permissions; ~/.cdx directory at 0o700      |
+| Token leakage to AI         | Sensitive file exclusion list + content sanitization   |
+| Session hijacking           | Short-lived Firebase ID tokens (1h) + refresh rotation |
+| Supply chain attacks        | Lockfile integrity; minimal production dependencies     |
+
+# Contributing
+
+## Workflow
+
+1. Fork the repository
+2. Create a feature branch: \`git checkout -b feat/your-feature\`
+3. Commit with conventional commits: \`feat:\`, \`fix:\`, \`docs:\`
+4. Open a pull request with a clear description
+
+## Checklist
+
+- [ ] Tests added/updated
+- [ ] No new sensitive data exposed
+- [ ] Documentation updated
+- [ ] \`npm audit\` passes
+
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Multi-model AI cascade with automatic fallback
+- Firebase Authentication (email/password)
+- Secure JWT session storage
+- Category-based configuration manager
+- Stack-aware file prioritization
+- Interactive post-processing improvement loop
+- GitHub repository integration (remote analysis + push)
+`;
+}
+
+// ─── Section writer ───────────────────────────────────────────────────────────
+async function writeDocFiles(cwd, doc, mainOutPath) {
+  const docsDir = path.join(cwd, "docs");
+  await fs.mkdir(docsDir, { recursive: true });
+
+  const SECTIONS = {
+    "README.md"             : extractSection(doc, "README\\.md") || extractSection(doc, "Project Overview"),
+    "docs/architecture.md"  : extractSection(doc, "Architecture"),
+    "docs/onboarding.md"    : extractSection(doc, "Onboarding"),
+    "docs/usage.md"         : extractSection(doc, "Usage"),
+    "docs/security.md"      : extractSection(doc, "Security"),
+    "docs/api-reference.md" : extractSection(doc, "API Reference"),
+    "docs/contributing.md"  : extractSection(doc, "Contributing"),
+    "docs/changelog.md"     : extractSection(doc, "Changelog"),
+  };
+
+  const written  = [];
+  const docFiles = {};
+
+  for (const [rel, content] of Object.entries(SECTIONS)) {
+    if (!content || content.trim().length < 30) continue;
+    const heading = path.basename(rel, ".md")
+      .split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+    const full    = `# ${heading}\n\n${content}\n`;
+    const absPath = path.join(cwd, rel);
+    try {
+      await fs.mkdir(path.dirname(absPath), { recursive: true });
+      await fs.writeFile(absPath, full, "utf8");
+      written.push(rel);
+      docFiles[rel] = full;
+    } catch {}
+  }
+
+  // Always write the full master doc
+  await fs.writeFile(mainOutPath, doc, "utf8");
+  docFiles[path.relative(cwd, mainOutPath)] = doc;
+
+  return { written, docFiles };
+}
+
+// ─── Interactive improvement loop ─────────────────────────────────────────────
+async function improvementLoop(apiKey, doc, cwd, mainOutPath, onProgress) {
+  const inquirer = (await import("inquirer").catch(() => null))?.default;
+  if (!inquirer) return doc;
+
+  const IMPROVE_CHOICES = [
+    { name: `  ${T.brand("◈")}  ${T.white("Expand a specific section")}         ${T.dim("Add more depth to any doc section")}`,   value: "expand" },
+    { name: `  ${T.brand("◈")}  ${T.white("Add code examples")}                 ${T.dim("Include realistic usage examples")}`,     value: "examples" },
+    { name: `  ${T.brand("◈")}  ${T.white("Improve security documentation")}    ${T.dim("Deeper threat model and controls")}`,     value: "security" },
+    { name: `  ${T.brand("◈")}  ${T.white("Add deployment guide")}              ${T.dim("Docker, CI/CD, cloud deployment")}`,      value: "deployment" },
+    { name: `  ${T.brand("◈")}  ${T.white("Custom instruction")}                ${T.dim("Type your own improvement request")}`,    value: "custom" },
+    { name: `  ${T.dim("◈")}  ${T.dim("Done — exit")}`,                                                                            value: "done" },
+  ];
+
+  const CANNED = {
+    expand    : "Significantly expand all sections that are fewer than 200 words. Add concrete details, specific file references, and technical depth throughout.",
+    examples  : "Add detailed, realistic code examples to the Usage section. Include at minimum: basic usage, advanced configuration, error handling pattern, and integration example.",
+    security  : "Substantially expand the Security section. Add a formal threat model table with at least 6 threats, detailed secrets management procedures, OWASP top-10 relevance, and incident response steps.",
+    deployment: "Add a comprehensive Deployment section covering: Docker containerization, environment variable management, CI/CD pipeline (GitHub Actions), staging vs production configuration, rollback procedures, and health check endpoints.",
+  };
+
+  let current = doc;
+  let iteration = 0;
+
+  while (true) {
+    console.log();
+    console.log(rule("─", T.dim));
+    console.log();
+    console.log(`   ${T.accent(ICONS.star)}  ${T.whiteBold("Documentation generated successfully!")}`);
+    console.log();
+
+    const { action } = await inquirer.prompt([{
+      type   : "list",
+      name   : "action",
+      message: T.brand("What would you like to do next?"),
+      choices: IMPROVE_CHOICES,
+      prefix : `   ${T.accent(ICONS.arrow)}`,
+    }]);
+
+    if (action === "done") break;
+
+    let instruction = CANNED[action] || "";
+
+    if (action === "custom") {
+      const { text } = await inquirer.prompt([{
+        type   : "input",
+        name   : "text",
+        message: T.brand("Enter your improvement instruction:"),
+        prefix : `   ${T.accent(ICONS.arrow)}`,
+        validate: v => v.trim().length > 5 || "Please enter a meaningful instruction.",
+      }]);
+      instruction = text.trim();
+    }
+
+    if (!instruction) continue;
+
+    console.log();
+    const spin = spinner("Applying improvement…").start();
+    try {
+      current = await pass4Improve(apiKey, current, instruction, { onProgress });
+      spin.ok(`Improvement applied (iteration ${++iteration})`);
+
+      // Re-write files with updated content
+      const { written } = await writeDocFiles(cwd, current, mainOutPath);
+      written.forEach(f => note(`Updated: ${f}`));
+    } catch (e) {
+      spin.fail(`Improvement failed: ${e.message}`);
+    }
+  }
+
+  return current;
+}
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+module.exports = async function createCommand(filename, cmdOpts = {}) {
+  const cwd     = process.cwd();
+  const outName = filename.endsWith(".md") ? filename : `${filename}.md`;
+  const outPath = path.resolve(cwd, outName);
+
+  const log = (msg) => { if (cmdOpts.onProgress) cmdOpts.onProgress(msg); else process.stdout.write(`\r   ${T.dim(msg)}                          \n`); };
+
+  // ── Load config ─────────────────────────────────────────────────────────────
+  const cfg         = store.load();
+  const apiKey      = cfg.geminiApiKey || null;
+  const aiModel     = cfg.geminiModel  || "gemini-2.5-pro-preview-03-25";
+  const ghToken     = cmdOpts.remoteGithub?.token || cfg.githubToken || null;
+  const ghRepoRaw   = cmdOpts.remoteGithub
+    ? `${cmdOpts.remoteGithub.owner}/${cmdOpts.remoteGithub.repo}`
+    : cfg.githubRepo || null;
+  const autoPush    = cmdOpts.push !== false && (cmdOpts.autoPush || cfg.autoPush || false);
+
+  // Parse owner/repo from "owner/repo" or "https://github.com/owner/repo"
+  let ghTarget = null;
+  if (ghRepoRaw) {
+    const m = ghRepoRaw.match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?(?:\/|$)/) ||
+              ghRepoRaw.match(/^([^/]+)\/([^/]+)$/);
+    if (m) ghTarget = { owner: m[1], repo: m[2] };
+  }
+
+  if (!apiKey) {
+    warn("Gemini API key not configured — using local documentation fallback.");
+    info("Run  cdx config  to configure your Gemini API key for AI-enhanced output.");
+  }
+
+  // ── Scan / Metadata phase ────────────────────────────────────────────────────
+  section("Scanning Project", cmdOpts.remoteGithub ? `${cmdOpts.remoteGithub.owner}/${cmdOpts.remoteGithub.repo}` : cwd);
+
+  let scanResult;
+  const scanSpin = spinner(cmdOpts.remoteGithub ? "Fetching repository tree via GitHub API…" : "Scanning local file system…").start();
+
+  try {
+    if (cmdOpts.remoteGithub) {
+      scanResult = await runRemotePipeline(cmdOpts.remoteGithub.owner, cmdOpts.remoteGithub.repo, cmdOpts.remoteGithub.token);
+    } else {
+      scanResult = await runLocalPipeline(cwd, { includeHidden: !!cmdOpts.all });
+    }
+    scanSpin.ok(`Scanned ${scanResult.raw.length} files → selected ${scanResult.selected.length} for analysis`);
+  } catch (e) {
+    scanSpin.fail(`Scan failed: ${e.message}`);
+    throw e;
+  }
+
+  const { raw, selected, stackInfo } = scanResult;
+
+  // Display scan summary
+  console.log();
+  table([
+    ["Total files scanned",  String(raw.length)],
+    ["Files selected for AI", String(selected.length)],
+    ["Detected stack",       badge(stackInfo.stack, "info")],
+    ["Stack signals",        stackInfo.reasons.slice(0,2).join("; ")],
+    ["Sensitive files",      String(raw.filter(m=>m.sensitive).length) + " (excluded from AI)"],
+    ["Test files",           String(raw.filter(m=>m.testFile).length)  + " (deprioritized)"],
+    ["Large files (chunked)", String(selected.filter(m=>m.chunked).length)],
+  ]);
+
+  // ── AI passes ────────────────────────────────────────────────────────────────
+  let doc = "";
+
+  if (apiKey) {
+    section("AI Documentation Generation", `Model: ${aiModel}`);
+
+    const aiOpts = {
+      onProgress: log,
+      maxRetries: 7,
+      baseDelay : 3500,
+    };
+
+    try {
+      // Pass 1 — per-file summaries
+      const p1spin = spinner("Pass 1 — Analyzing individual modules…").start();
+      let summaries;
+      try {
+        summaries = await pass1FileSummaries(apiKey, selected, aiOpts);
+        p1spin.ok(`Pass 1 complete — summarized ${summaries.length} modules`);
+      } catch (e) {
+        p1spin.fail(`Pass 1 failed: ${e.message}`);
+        throw e;
+      }
+
+      // Pass 2 — system overview
+      const p2spin = spinner("Pass 2 — Synthesizing system architecture…").start();
+      let overview;
+      try {
+        overview = await pass2SystemOverview(apiKey, selected, summaries, stackInfo, aiOpts);
+        p2spin.ok("Pass 2 complete — architecture overview generated");
+      } catch (e) {
+        p2spin.fail(`Pass 2 failed: ${e.message}`);
+        throw e;
+      }
+
+      // Pass 3 — full documentation suite
+      const p3spin = spinner("Pass 3 — Composing comprehensive documentation suite…").start();
+      try {
+        doc = await pass3FullDocs(apiKey, overview, summaries, selected, stackInfo, aiOpts);
+        p3spin.ok("Pass 3 complete — full documentation suite generated");
+      } catch (e) {
+        p3spin.fail(`Pass 3 failed: ${e.message}`);
+        throw e;
+      }
+
+    } catch (e) {
+      err(`AI generation failed: ${e.message}`);
+      if (e.code === "RATE_LIMIT_EXCEEDED") {
+        warn("Rate limit exhausted. Falling back to local documentation generation.");
+      } else {
+        warn("Falling back to local documentation generation.");
+      }
+      doc = generateLocalDocs(selected, stackInfo);
+    }
+  } else {
+    doc = generateLocalDocs(selected, stackInfo);
+  }
+
+  // ── Write files ──────────────────────────────────────────────────────────────
+  section("Writing Documentation Files");
+
+  const writeSpin = spinner("Writing documentation files to disk…").start();
+  let docFiles = {};
+  try {
+    const result = await writeDocFiles(cwd, doc, outPath);
+    docFiles = result.docFiles;
+    writeSpin.ok(`Wrote ${result.written.length + 1} documentation files`);
+    result.written.forEach(f => note(`  ${f}`));
+    note(`  ${outName}  (master document)`);
+  } catch (e) {
+    writeSpin.fail(`Write failed: ${e.message}`);
+    throw e;
+  }
+
+  // ── GitHub push ──────────────────────────────────────────────────────────────
+  if (ghToken && ghTarget && autoPush) {
+    section("GitHub Push", `${ghTarget.owner}/${ghTarget.repo}`);
+    const pushSpin = spinner(`Pushing documentation to ${ghTarget.owner}/${ghTarget.repo}…`).start();
+    try {
+      const { pushed, failed } = await pushToGitHub(ghToken, ghTarget.owner, ghTarget.repo, docFiles, log);
+      pushSpin.ok(`Pushed ${pushed.length} file(s) to GitHub`);
+      if (failed.length) {
+        failed.forEach(f => warn(`Push failed: ${f.path} — ${f.error.split("\n")[0]}`));
+      }
+    } catch (e) {
+      pushSpin.fail(`GitHub push failed: ${e.message}`);
+    }
+  } else if (ghToken && ghTarget && !autoPush) {
+    note(`GitHub push skipped (auto-push disabled). Run with --push to push now.`);
+  }
+
+  // ── Interactive improvement loop (only in terminal, not in piped/non-TTY mode) ──
+  if (apiKey && process.stdout.isTTY && !cmdOpts.noInteractive) {
+    await improvementLoop(apiKey, doc, cwd, outPath, log);
+  }
+
+  // ── Final summary ────────────────────────────────────────────────────────────
+  section("Generation Complete");
+  ok(`Master document: ${chalk.cyan(outName)}`);
+  if (cfg.generateSubDocs !== false) {
+    ok("Sub-documents written to docs/");
+  }
+  note(`Total files analyzed: ${raw.length}`);
+  note(`AI model used: ${apiKey ? aiModel : "local fallback (no API key)"}`);
+
+  footer();
+};