docit-ai 1.0.0

package/src/ai/prompts.ts

@@ -0,0 +1,123 @@
+/**
+ * AI Prompts Module
+ * Contains system prompts for the three persona-based views.
+ */
+
+export const STRATEGIC_VIEW_PROMPT = `You are a technical writer creating documentation for Project Managers.
+
+Your task is to analyze code skeletons and produce a "Strategic View" summary.
+
+RULES:
+- Focus on business value and project status
+- NO code snippets allowed
+- Use bullet points and bold text for key deliverables
+- Include a "What this feature enables" section
+- Provide a "Completeness Score" (0-100%) based on:
+  - Function implementation status
+  - TODO comments remaining
+  - Interface completeness
+
+OUTPUT FORMAT:
+## Feature: [Feature Name]
+
+**What This Enables:**
+- [Business capability 1]
+- [Business capability 2]
+
+**Status:**
+- **Completeness Score:** XX%
+- [Key status points]
+
+**Key Deliverables:**
+- [Deliverable 1]
+- [Deliverable 2]
+`;
+
+export const TECHNICAL_VIEW_PROMPT = `You are a technical writer creating documentation for Developers.
+
+Your task is to analyze code skeletons and produce a "Technical View" reference.
+
+RULES:
+- Focus on architecture and integration details
+- Include detailed function signatures
+- Provide dependency maps where applicable
+- Include "How to use" code examples
+- Explain internal logic when relevant
+- Use strict Markdown with syntax highlighting
+
+OUTPUT FORMAT:
+## Module: [Module Name]
+
+### Overview
+[Brief description of the module's purpose]
+
+### Functions
+
+#### \`functionName(params): returnType\`
+**Description:** [What this function does]
+
+**Parameters:**
+- \`param1\` (Type): Description
+- \`param2\` (Type): Description
+
+**Returns:** Type - Description
+
+**Example:**
+\`\`\`typescript
+// Usage example
+\`\`\`
+
+### Dependencies
+- [Dependency 1]: [Purpose]
+- [Dependency 2]: [Purpose]
+
+### Internal Logic
+[Explanation of key algorithms or patterns]
+`;
+
+export const PERSONAL_VIEW_PROMPT = `You are a technical writer creating documentation for Solo Developers.
+
+Your task is to analyze code skeletons and produce a "Personal View" roadmap.
+
+RULES:
+- Focus on productivity and actionable items
+- Generate a To-Do list from TODO comments in code
+- Create a "Technical Debt" summary
+- Use concise, checklist-style formatting
+- Prioritize items by importance
+
+OUTPUT FORMAT:
+## Personal Roadmap: [File/Module Name]
+
+### Action Items
+- [ ] [High Priority] Task from TODO comment
+- [ ] [Medium Priority] Improvement suggestion
+- [ ] [Low Priority] Nice-to-have enhancement
+
+### Technical Debt
+| Issue | Location | Effort | Impact |
+|-------|----------|--------|--------|
+| [Description] | Line X | Low/Med/High | Low/Med/High |
+
+### Quick Notes
+- [Notable patterns or concerns]
+- [Suggestions for refactoring]
+`;
+
+export function getPromptForView(
+  view: "strategic" | "technical" | "personal",
+): string {
+  switch (view) {
+    case "strategic":
+      return STRATEGIC_VIEW_PROMPT;
+    case "technical":
+      return TECHNICAL_VIEW_PROMPT;
+    case "personal":
+      return PERSONAL_VIEW_PROMPT;
+    default:
+      throw new Error(`Unknown view type: ${view}`);
+  }
+}
+
+export const VIEWS = ["strategic", "technical", "personal"] as const;
+export type ViewType = (typeof VIEWS)[number];

package/src/cli/index.ts

@@ -0,0 +1,552 @@
+import { Command } from "commander";
+import * as dotenv from "dotenv";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import * as crypto from "crypto";
+import * as readline from "readline";
+import { getModifiedTypeScriptFiles } from "../scanner/index.js";
+import { analyzeFile, formatSkeletonForLLM } from "../parser/extractor.js";
+import { formatDocumentation, writeDocumentation } from "../formatter/index.js";
+
+dotenv.config();
+
+/**
+ * CLI Module
+ * Implements the `docit` commands using Commander.
+ */
+
+interface LockFileEntry {
+  hash: string;
+  lastUpdated: string;
+}
+
+interface LockFile {
+  [filePath: string]: LockFileEntry;
+}
+
+interface Credentials {
+  token: string;
+  email: string;
+  apiUrl: string;
+}
+
+const LOCK_FILE_PATH = "./docit.lock";
+const CREDENTIALS_DIR = path.join(os.homedir(), ".docit");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
+const DEFAULT_API_URL = "http://localhost:3001";
+
+function loadLockFile(): LockFile {
+  try {
+    if (fs.existsSync(LOCK_FILE_PATH)) {
+      const content = fs.readFileSync(LOCK_FILE_PATH, "utf-8");
+      return JSON.parse(content) as LockFile;
+    }
+  } catch {
+    // Ignore parse errors, return empty lock file
+  }
+  return {};
+}
+
+function saveLockFile(lockFile: LockFile): void {
+  fs.writeFileSync(LOCK_FILE_PATH, JSON.stringify(lockFile, null, 2), "utf-8");
+}
+
+function computeFileHash(filePath: string): string {
+  const content = fs.readFileSync(filePath, "utf-8");
+  return crypto.createHash("md5").update(content).digest("hex");
+}
+
+function shouldProcessFile(filePath: string, lockFile: LockFile): boolean {
+  const currentHash = computeFileHash(filePath);
+  const entry = lockFile[filePath];
+
+  if (!entry) return true;
+  return entry.hash !== currentHash;
+}
+
+function loadCredentials(): Credentials | null {
+  try {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+      const content = fs.readFileSync(CREDENTIALS_FILE, "utf-8");
+      return JSON.parse(content) as Credentials;
+    }
+  } catch {
+    // Ignore errors
+  }
+  return null;
+}
+
+function saveCredentials(credentials: Credentials): void {
+  if (!fs.existsSync(CREDENTIALS_DIR)) {
+    fs.mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  }
+  fs.writeFileSync(
+    CREDENTIALS_FILE,
+    JSON.stringify(credentials, null, 2),
+    "utf-8",
+  );
+}
+
+function deleteCredentials(): void {
+  if (fs.existsSync(CREDENTIALS_FILE)) {
+    fs.unlinkSync(CREDENTIALS_FILE);
+  }
+}
+
+async function prompt(question: string, hidden = false): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    if (hidden) {
+      process.stdout.write(question);
+      let input = "";
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.on("data", (char) => {
+        const charStr = char.toString();
+        if (charStr === "\n" || charStr === "\r" || charStr === "\u0004") {
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+          console.log();
+          rl.close();
+          resolve(input);
+        } else if (charStr === "\u007F" || charStr === "\b") {
+          input = input.slice(0, -1);
+          process.stdout.clearLine(0);
+          process.stdout.cursorTo(0);
+          process.stdout.write(question + "*".repeat(input.length));
+        } else {
+          input += charStr;
+          process.stdout.write("*");
+        }
+      });
+    } else {
+      rl.question(question, (answer) => {
+        rl.close();
+        resolve(answer);
+      });
+    }
+  });
+}
+
+async function apiRequest(
+  endpoint: string,
+  options: {
+    method?: string;
+    body?: object;
+    token?: string;
+    apiUrl?: string;
+  } = {},
+): Promise<{ ok: boolean; status: number; data: Record<string, unknown> }> {
+  const { method = "GET", body, token, apiUrl = DEFAULT_API_URL } = options;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+
+  const fetchOptions: RequestInit = {
+    method,
+    headers,
+  };
+
+  if (body) {
+    fetchOptions.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(`${apiUrl}${endpoint}`, fetchOptions);
+
+  const data = (await response.json()) as Record<string, unknown>;
+  return { ok: response.ok, status: response.status, data };
+}
+
+export function createCli(): Command {
+  const program = new Command();
+
+  program
+    .name("docit")
+    .description("AI-powered documentation generator")
+    .version("1.0.0");
+
+  // Register command
+  program
+    .command("register")
+    .description("Create a new Docit account")
+    .option("--api-url <url>", "API server URL", DEFAULT_API_URL)
+    .action(async (options: { apiUrl: string }) => {
+      console.log("📝 Create your Docit account\n");
+
+      const email = await prompt("Email: ");
+      const password = await prompt("Password: ", true);
+      const name = await prompt("Name (optional): ");
+      const country = await prompt("Country (e.g., Nigeria, USA): ");
+
+      console.log("\n🔄 Creating account...");
+
+      const result = await apiRequest("/api/auth/register", {
+        method: "POST",
+        body: {
+          email,
+          password,
+          name: name || undefined,
+          country: country || undefined,
+        },
+        apiUrl: options.apiUrl,
+      });
+
+      if (!result.ok) {
+        console.error(
+          `❌ Error: ${result.data["error"] ?? "Registration failed"}`,
+        );
+        process.exit(1);
+      }
+
+      const { token, user } = result.data as {
+        token: string;
+        user: { email: string; credits: number };
+      };
+
+      saveCredentials({ token, email: user.email, apiUrl: options.apiUrl });
+
+      console.log(`\n✅ Account created successfully!`);
+      console.log(`   Email: ${user.email}`);
+      console.log(`   Credits: ${user.credits}`);
+      console.log(`\nYou can now run 'docit sync' to generate documentation.`);
+    });
+
+  // Login command
+  program
+    .command("login")
+    .description("Login to your Docit account")
+    .option("--api-url <url>", "API server URL", DEFAULT_API_URL)
+    .action(async (options: { apiUrl: string }) => {
+      console.log("🔐 Login to Docit\n");
+
+      const email = await prompt("Email: ");
+      const password = await prompt("Password: ", true);
+
+      console.log("\n🔄 Logging in...");
+
+      const result = await apiRequest("/api/auth/login", {
+        method: "POST",
+        body: { email, password },
+        apiUrl: options.apiUrl,
+      });
+
+      if (!result.ok) {
+        console.error(`❌ Error: ${result.data["error"] ?? "Login failed"}`);
+        process.exit(1);
+      }
+
+      const { token, user } = result.data as {
+        token: string;
+        user: { email: string; credits: number };
+      };
+
+      saveCredentials({ token, email: user.email, apiUrl: options.apiUrl });
+
+      console.log(`\n✅ Logged in successfully!`);
+      console.log(`   Email: ${user.email}`);
+      console.log(`   Credits: ${user.credits}`);
+    });
+
+  // Logout command
+  program
+    .command("logout")
+    .description("Logout from your Docit account")
+    .action(() => {
+      deleteCredentials();
+      console.log("✅ Logged out successfully.");
+    });
+
+  // Status command
+  program
+    .command("status")
+    .description("Check your account status and credits")
+    .action(async () => {
+      const credentials = loadCredentials();
+
+      if (!credentials) {
+        console.error("❌ Not logged in. Run 'docit login' first.");
+        process.exit(1);
+      }
+
+      const result = await apiRequest("/api/auth/me", {
+        token: credentials.token,
+        apiUrl: credentials.apiUrl,
+      });
+
+      if (!result.ok) {
+        console.error("❌ Session expired. Please login again.");
+        deleteCredentials();
+        process.exit(1);
+      }
+
+      const { user } = result.data as {
+        user: { email: string; credits: number };
+      };
+
+      console.log(`📊 Account Status`);
+      console.log(`   Email: ${user.email}`);
+      console.log(`   Credits: ${user.credits}`);
+    });
+
+  // Sync command
+  program
+    .command("sync")
+    .description("Sync documentation with code changes")
+    .option("-f, --force", "Force regeneration of all documentation")
+    .option(
+      "-o, --output <path>",
+      "Output path for documentation",
+      "./DOCIT.md",
+    )
+    .option("--dry-run", "Show what would be processed without making changes")
+    .action(
+      async (options: {
+        force?: boolean;
+        output: string;
+        dryRun?: boolean;
+      }) => {
+        const credentials = loadCredentials();
+
+        if (!credentials) {
+          console.error(
+            "❌ Not logged in. Run 'docit login' or 'docit register' first.",
+          );
+          process.exit(1);
+        }
+
+        console.log("🔍 Scanning for modified files...");
+
+        const modifiedFiles = await getModifiedTypeScriptFiles(".");
+
+        if (modifiedFiles.length === 0) {
+          console.log("✅ No modified TypeScript files found.");
+          return;
+        }
+
+        console.log(`📁 Found ${modifiedFiles.length} modified file(s):`);
+        modifiedFiles.forEach((f) =>
+          console.log(`   - ${path.relative(".", f)}`),
+        );
+
+        const lockFile = options.force ? {} : loadLockFile();
+        const filesToProcess = modifiedFiles.filter(
+          (f) => options.force ?? shouldProcessFile(f, lockFile),
+        );
+
+        if (filesToProcess.length === 0) {
+          console.log(
+            "✅ All files are up to date (use --force to regenerate).",
+          );
+          return;
+        }
+
+        if (options.dryRun) {
+          console.log("\n🔮 Dry run - would process:");
+          filesToProcess.forEach((f) =>
+            console.log(`   - ${path.relative(".", f)}`),
+          );
+          console.log(`\n   Credits needed: ${filesToProcess.length}`);
+          return;
+        }
+
+        console.log(`\n📝 Processing ${filesToProcess.length} file(s)...`);
+
+        // Analyze all files
+        const analyses = filesToProcess.map((f) => {
+          console.log(`   Parsing: ${path.relative(".", f)}`);
+          return analyzeFile(f);
+        });
+
+        // Combine all skeletons
+        const combinedSkeleton = analyses
+          .map((a) => formatSkeletonForLLM(a))
+          .join("\n\n---\n\n");
+
+        console.log("\n🤖 Generating documentation with AI...");
+
+        // Call backend API
+        const result = await apiRequest("/api/generate", {
+          method: "POST",
+          body: {
+            codeSkeleton: combinedSkeleton,
+            fileCount: filesToProcess.length,
+          },
+          token: credentials.token,
+          apiUrl: credentials.apiUrl,
+        });
+
+        if (!result.ok) {
+          if (result.status === 402) {
+            const { required, available } = result.data as {
+              required: number;
+              available: number;
+            };
+            console.error(`\n❌ Insufficient credits!`);
+            console.error(`   Required: ${required}`);
+            console.error(`   Available: ${available}`);
+            console.error(`\n   Purchase more credits to continue.`);
+            process.exit(1);
+          }
+          console.error(
+            `\n❌ Error: ${result.data["error"] ?? "Generation failed"}`,
+          );
+          process.exit(1);
+        }
+
+        const { results, creditsUsed, creditsRemaining } = result.data as {
+          results: Array<{ view: string; content: string }>;
+          creditsUsed: number;
+          creditsRemaining: number;
+        };
+
+        console.log("📄 Formatting documentation...");
+
+        const projectName = path.basename(process.cwd());
+        const documentation = formatDocumentation(
+          results.map((r) => ({
+            view: r.view as "strategic" | "technical" | "personal",
+            content: r.content,
+          })),
+          { projectName },
+        );
+
+        writeDocumentation(documentation, options.output);
+        console.log(`✅ Documentation written to ${options.output}`);
+        console.log(
+          `💰 Credits used: ${creditsUsed} | Remaining: ${creditsRemaining}`,
+        );
+
+        // Update lock file
+        const newLockFile: LockFile = { ...lockFile };
+        for (const filePath of filesToProcess) {
+          newLockFile[filePath] = {
+            hash: computeFileHash(filePath),
+            lastUpdated: new Date().toISOString(),
+          };
+        }
+        saveLockFile(newLockFile);
+        console.log("🔒 Lock file updated.");
+      },
+    );
+
+  // Init command (for reference)
+  program
+    .command("init")
+    .description("Initialize Docit in the current project")
+    .action(() => {
+      const gitignorePath = "./.gitignore";
+
+      if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, "utf-8");
+        if (!content.includes("docit.lock")) {
+          fs.appendFileSync(gitignorePath, "\ndocit.lock\n");
+          console.log("✅ Added docit.lock to .gitignore");
+        }
+      } else {
+        fs.writeFileSync(gitignorePath, "docit.lock\n", "utf-8");
+        console.log("✅ Created .gitignore");
+      }
+
+      console.log("\n🎉 Docit initialized! Next steps:");
+      console.log("   1. Run 'docit register' to create an account");
+      console.log("   2. Run 'docit sync' to generate documentation");
+    });
+
+  // Subscribe command
+  program
+    .command("subscribe")
+    .description("Subscribe to get more credits")
+    .action(async () => {
+      const credentials = loadCredentials();
+
+      if (!credentials) {
+        console.error("❌ Not logged in. Run 'docit login' first.");
+        process.exit(1);
+      }
+
+      console.log("💳 Docit Subscription Plans\n");
+
+      // Get plans from API
+      const plansResult = await apiRequest("/api/payment/plans", {
+        apiUrl: credentials.apiUrl,
+      });
+
+      if (!plansResult.ok) {
+        console.error("❌ Failed to fetch plans");
+        process.exit(1);
+      }
+
+      const { plans } = plansResult.data as {
+        plans: Array<{
+          id: string;
+          name: string;
+          amount: number;
+          currency: string;
+          credits: number;
+          description: string;
+        }>;
+      };
+
+      console.log("Available plans:");
+      plans.forEach((plan, index) => {
+        const symbol = plan.currency === "NGN" ? "₦" : "$";
+        console.log(
+          `   ${index + 1}. ${plan.name} - ${symbol}${plan.amount.toLocaleString()}/${plan.currency} (${plan.credits} credits)`,
+        );
+      });
+
+      const choice = await prompt("\nSelect a plan (1 or 2): ");
+      const selectedIndex = parseInt(choice, 10) - 1;
+
+      if (
+        isNaN(selectedIndex) ||
+        selectedIndex < 0 ||
+        selectedIndex >= plans.length
+      ) {
+        console.error("❌ Invalid selection");
+        process.exit(1);
+      }
+
+      const selectedPlan = plans[selectedIndex];
+      if (!selectedPlan) {
+        console.error("❌ Plan not found");
+        process.exit(1);
+      }
+
+      console.log(`\n🔄 Initiating payment for ${selectedPlan.name}...`);
+
+      const paymentResult = await apiRequest("/api/payment/initiate", {
+        method: "POST",
+        body: { planId: selectedPlan.id },
+        token: credentials.token,
+        apiUrl: credentials.apiUrl,
+      });
+
+      if (!paymentResult.ok) {
+        console.error(
+          `❌ Error: ${paymentResult.data["error"] ?? "Payment failed"}`,
+        );
+        process.exit(1);
+      }
+
+      const { paymentLink } = paymentResult.data as { paymentLink: string };
+
+      console.log("\n✅ Payment link generated!");
+      console.log(
+        `\n🔗 Open this link to complete payment:\n   ${paymentLink}`,
+      );
+      console.log("\nAfter payment, your credits will be automatically added.");
+    });
+
+  return program;
+}