legacyver 2.1.6 → 2.1.8

package/README.md

@@ -1,199 +1,96 @@
-# Legacyver
+# 🚀 Legacyver
 
-Auto-generate technical documentation for legacy and undocumented codebases using AST parsing + LLMs.
-
-```bash
-npx legacyver analyze ./src
-```
-
-No documentation written beforehand. No configuration required. One command.
+**AI-powered CLI tool** untuk generate dokumentasi teknis secara otomatis dari codebase yang sudah ada (legacy) atau tidak memiliki dokumentasi. Menggunakan parsing AST yang mendalam dikombinasikan dengan LLM (Groq, Gemini, Ollama, dll.) untuk menjelaskan struktur, logika, dan pola kode kamu.
 
 ---
 
-## Install
+## ⚡ Panduan Cepat (Step-by-Step)
 
+Ikuti urutan ini untuk membuat dokumentasi kamu siap dalam hitungan menit:
+
+### 1. Instalasi
+Instal package secara global melalui npm:
 ```bash
 npm install -g legacyver
 ```
+*Atau gunakan `npx legacyver` jika kamu tidak ingin menginstalnya secara global.*
 
-Or use without installing:
-
+### 2. Login (Cloud Sync)
+Masuk ke akun Legacyver kamu untuk mengaktifkan sinkronisasi cloud dan menyimpan dokumentasi di dashboard:
 ```bash
-npx legacyver analyze ./src
+legacyver login
 ```
 
----
-
-## Quick Start
-
-**1. Initialize (saves your API key):**
-
+### 3. Inisialisasi Konfigurasi
+Jalankan wizard setup untuk menyimpan API key (Groq, Gemini, dll.) dan membuat file konfigurasi `.legacyverrc`:
 ```bash
 legacyver init
 ```
 
-**2. Analyze a codebase:**
-
+### 4. Analisis & Generate
+Jalankan perintah utama untuk menganalisis folder project kamu:
 ```bash
-legacyver analyze ./src
-```
-
-**3. View the output:**
-
-```
-legacyver-docs/
-  index.md        ← project overview + dependency graph + route map (Laravel)
-  SUMMARY.md      ← GitBook/Docusaurus compatible table of contents
-  src/
-    app.md
-    routes/users.md
-    ...
+legacyver analyze ./src --incremental
 ```
+*Flag `--incremental` memastikan hanya file yang dimodifikasi yang akan diproses ulang di jalankan berikutnya (lebih cepat & hemat).*
 
 ---
 
-## CLI Commands
+## 🛠️ Daftar Perintah (CLI Commands)
 
-### `legacyver analyze <dir>`
+### `legacyver analyze [target]`
+Perintah utama untuk memindai codebase dan membuat dokumentasi.
 
-Run the full documentation pipeline.
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--out <dir>` | `./legacyver-docs` | Output directory |
-| `--format <fmt>` | `markdown` | Output format: `markdown`, `html`, `json` |
-| `--provider <p>` | `openrouter` | LLM provider: `openrouter`, `ollama` |
-| `--model <id>` | `meta-llama/llama-3.3-70b-instruct:free` | Model ID |
-| `--incremental` | `false` | Skip files unchanged since last run |
-| `--dry-run` | `false` | Estimate cost without calling LLM |
-| `--concurrency <n>` | `3` | Max parallel LLM requests |
-| `--max-file-size <kb>` | `500` | Skip files larger than this |
-| `--no-confirm` | — | Skip cost confirmation prompt |
-| `--verbose` | `false` | Enable debug logging |
+| Flag | Default | Deskripsi |
+|------|---------|-----------|
+| `--out <dir>` | `./legacyver-docs` | Folder output hasil dokumentasi |
+| `--format <fmt>` | `markdown` | Format output: `markdown`, `html`, `json` |
+| `--provider <p>` | `groq` | Provider AI: `groq`, `gemini`, `ollama`, `openrouter` |
+| `--incremental` | `false` | Hanya proses file yang berubah (lebih cepat) |
+| `--dry-run` | `false` | Estimasi penggunaan token tanpa memanggil AI |
+| `--no-confirm` | — | Lewati konfirmasi estimasi biaya |
 
 ### `legacyver init`
-
-Interactive wizard. Detects existing `.legacyverrc` and warns before overwriting. Saves API key to OS user config.
+Wizard interaktif untuk setup API key dan preferensi lokal.
 
 ### `legacyver providers`
+Cek status API key dan daftar model AI yang tersedia.
 
-List all supported providers, API key status, and per-model pricing.
+### `legacyver login / logout`
+Kelola sesi untuk sinkronisasi dokumentasi ke cloud.
 
-### `legacyver cache clear`
+---
 
-Delete the `.legacyver-cache/` directory to force full re-analysis on next run.
+## 🏗️ Dukungan Framework & Bahasa
 
-### `legacyver --version`
+| Kategori | Item yang Didukung |
+|----------|--------------------|
+| **Bahasa** | JavaScript, TypeScript, PHP, Python, Java, Go |
+| **Framework** | **Laravel** (Deteksi Otomatis Routes, Models, ERD), **Express** |
+| **Integrasi** | GitHub Actions, GitBook, Docusaurus |
 
-Print the installed version.
+### 🐘 Integrasi Mendalam Laravel
+Jika file `artisan` terdeteksi, Legacyver otomatis mengekstrak:
+- **Route Maps**: Daftar lengkap method, URI, dan Controller.
+- **ER Diagrams**: Membuat diagram Mermaid otomatis untuk Model kamu.
+- **Service Providers**: Mendokumentasikan binding dependency yang kompleks.
 
 ---
 
-## `.legacyverrc` Schema
-
-Create a `.legacyverrc` (JSON or YAML) in your project root:
+## ⚙️ Konfigurasi (`.legacyverrc`)
+Sesuaikan alur kerja kamu dengan file konfigurasi:
 
 ```json
 {
-  "provider": "openrouter",
-  "model": "meta-llama/llama-3.3-70b-instruct:free",
+  "provider": "gemini",
+  "model": "gemini-1.5-flash",
   "format": "markdown",
-  "out": "./legacyver-docs",
-  "concurrency": 3,
-  "maxFileSizeKb": 500,
-  "incremental": true
+  "incremental": true,
+  "out": "./legacyver-docs"
 }
 ```
 
-All fields are optional. CLI flags override file config.
-
-Also supported: `legacyver.config.js`, `legacyver.config.yaml`.
-
----
-
-## Supported Languages
-
-| Language | Extensions | Framework Support |
-|----------|-----------|-------------------|
-| JavaScript | `.js`, `.jsx`, `.mjs` | Express (auto-detected) |
-| TypeScript | `.ts`, `.tsx` | — |
-| Python | `.py` | — |
-| Java | `.java` | — |
-| Go | `.go` | — |
-| PHP | `.php`, `.blade.php` | Laravel (auto-detected) |
-
-**Laravel extras:** When an `artisan` file is detected, Legacyver automatically extracts:
-- Route Map (Method, URI, Controller, Middleware, Route Name)
-- Model Relationships (as Mermaid `erDiagram`)
-- Service Provider Bindings
-
 ---
 
-## Supported LLM Providers
-
-| Provider | Env Var | Notes |
-|----------|---------|-------|
-| OpenRouter | `OPENROUTER_API_KEY` | Default. Free models available (`:free` suffix). Get a key at [openrouter.ai/keys](https://openrouter.ai/keys) |
-| Ollama | — | Local/offline. Requires Ollama running: `ollama serve` |
-
-**Free usage:** The default model `meta-llama/llama-3.3-70b-instruct:free` is free via OpenRouter (rate-limited). Legacyver automatically caps concurrency to 1 for free models.
-
----
-
-## Ignore Files
-
-Create a `.legacyverignore` in your project root using gitignore syntax:
-
-```
-# .legacyverignore
-dist/
-build/
-coverage/
-*.min.js
-```
-
-See `.legacyverignore.example` for a documented example.
-
----
-
-## CI/CD Integration
-
-```yaml
-# GitHub Actions example
-- name: Generate docs
-  env:
-    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
-  run: |
-    npx legacyver analyze ./src --no-confirm --incremental --out ./docs
-```
-
-Legacyver detects non-TTY environments and disables spinners/progress bars automatically (plain log output only).
-
----
-
-## How It Works
-
-1. **Crawl** — `fast-glob` walks the directory, respects `.legacyverignore`
-2. **Parse** — Regex/heuristic AST extracts facts: function names, params, complexity scores, imports, exports, call patterns
-3. **PKG** — Assembles a Project Knowledge Graph linking all facts
-4. **LLM** — Sends grounded facts + raw source to LLM; system prompt enforces anti-hallucination contract
-5. **Validate** — Post-generation checks: hallucination detection, completeness check (all exports documented)
-6. **Render** — Writes Markdown/HTML/JSON to output directory
-
-**Design principle:** The LLM is a _writer_, not an analyst. AST extracts facts; LLM only explains them.
-
----
-
-## Contributing
-
-```bash
-git clone https://github.com/user/legacyver
-npm install
-npx vitest run
-```
-
----
-
-## License
-
-MIT
+## 📄 Lisensi
+MIT License. Dibuat dengan ❤️ untuk developer yang berjuang melawan legacy code.

package/bin/legacyver.js

@@ -69,4 +69,12 @@ program
   .description('Log out and stop syncing docs to the cloud')
   .action(logoutCmd);
 
+// push command
+const pushCmd = require('../src/cli/commands/push');
+program
+  .command('push [target]')
+  .description('Manually push generated docs to the cloud database')
+  .option('--out <dir>', 'Docs output directory to read from', './legacyver-docs')
+  .action(pushCmd);
+
 program.parse(process.argv);

package/legacyver-docs/components.md

@@ -1,51 +1,50 @@
 ## Overview
-The components.tsx file contains a collection of reusable React components and a utility function for formatting currency. 
+This file contains React components and a utility function for formatting currency. The components include a Button and a UserCard.
 
 ## Functions
 ### Button
-The Button function is a React component that renders a button element with a specified label, click handler, and variant.
+The Button component is a React functional component that renders a button element.
 #### Parameters
-| Name | Type | Description |
+| Parameter | Type | Description |
 | --- | --- | --- |
-| label | string | The text displayed on the button |
-| onClick | () => void | The function called when the button is clicked |
-| disabled | boolean | Whether the button is disabled (optional, default: false) |
-| variant | 'primary' | 'secondary' | 'danger' | The style variant of the button (optional, default: 'primary') |
+| label | string | The text to display on the button |
+| onClick | () => void | The function to call when the button is clicked |
+| disabled | boolean | Optional, whether the button is disabled |
+| variant | 'primary' | 'secondary' | 'danger' | Optional, the style variant of the button |
 #### Return Value
-A React button element
+The Button component returns a JSX button element.
 
 ### UserCard
-The UserCard function is a React component that fetches and displays user data based on a provided user ID.
+The UserCard component is a React functional component that fetches user data and displays it in a card.
 #### Parameters
-| Name | Type | Description |
+| Parameter | Type | Description |
 | --- | --- | --- |
-| userId | number | The ID of the user to fetch and display |
-| onClose | () => void | The function called when the close button is clicked |
+| userId | number | The ID of the user to fetch |
+| onClose | () => void | The function to call when the close button is clicked |
 #### Return Value
-A React element containing the user's name, email, and a close button, or a loading indicator if the data is not yet available
+The UserCard component returns a JSX div element containing the user's data or a loading/error message.
 
 ### formatCurrency
-The formatCurrency function formats a given amount as a currency string.
+The formatCurrency function formats a number as a currency string.
 #### Parameters
-| Name | Type | Description |
+| Parameter | Type | Description |
 | --- | --- | --- |
 | amount | number | The amount to format |
-| currency | string | The currency to use for formatting (optional, default: 'USD') |
+| currency | string | Optional, the currency to use (default: 'USD') |
 #### Return Value
-A string representing the formatted amount
+The formatCurrency function returns a string representing the formatted currency amount.
 
 ## Dependencies
 * React
-* useState
-* useEffect
+* Intl.NumberFormat
 
 ## Usage Example
-No clear usage example is visible in the provided code, but the components can be used as follows:
+No clear usage example is visible in the provided code. However, components can be used as follows:
 ```jsx
 import { Button, UserCard, formatCurrency } from './components';
 
 const App = () => {
-  const handleButtonClick = () => {
+  const handleButtonClicked = () => {
     console.log('Button clicked');
   };
 
@@ -55,9 +54,9 @@ const App = () => {
 
   return (
     <div>
-      <Button label="Click me" onClick={handleButtonClick} />
-      <UserCard userId={123} onClose={handleUserCardClose} />
-      <p>Formatted amount: {formatCurrency(12345.67)}</p>
+      <Button label="Click me" onClick={handleButtonClicked} />
+      <UserCard userId={1} onClose={handleUserCardClose} />
+      <p>Formatted currency: {formatCurrency(1000)}</p>
     </div>
   );
 };

package/legacyver-docs/index.md

@@ -2,7 +2,7 @@
 
 **Primary language:** typescript  
 **Total files:** 1  
-**Analyzed at:** 2026-02-21T18:11:04.560Z  
+**Analyzed at:** 2026-02-22T03:13:37.724Z  
 
 ## Files
 

package/nul

@@ -0,0 +1 @@
+/usr/bin/bash: line 1: type: %USERPROFILE%\.legacyver\session.json: not found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "legacyver",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "AI-powered CLI tool to auto-generate technical documentation from legacy/undocumented codebases",
   "main": "src/index.js",
   "bin": {

package/src/api/auth.js

@@ -1,69 +1,69 @@
 'use strict';
 
+const crypto = require('crypto');
 const { Pool } = require('pg');
 const dbConfig = require('../db/config');
 
 /**
- * Find or create a user by email.
- * Direct DB approach — no web API dependency.
- * @param {string} email
- * @param {string} username
+ * Validate a CLI session token against app.user_sessions.
+ * Returns user info if valid, null if expired/revoked/not found.
+ *
+ * @param {string} token  raw token from ~/.legacyver/session.json
  * @param {object} [opts]          optional overrides for testing
- * @param {object} [opts.pool]     pg Pool instance (skips internal pool creation)
- * @returns {Promise<{userId: string, username: string, email: string, isNew: boolean}>}
+ * @param {object} [opts.pool]     pg Pool instance
+ * @returns {Promise<{userId: string, username: string, email: string} | null>}
  */
-async function loginOrRegister(email, username, opts) {
+async function validateToken(token, opts) {
+  if (!token) return null;
+
   const ownPool = !(opts && opts.pool);
   const pool = (opts && opts.pool) || new Pool(dbConfig);
   try {
-    // Try to find existing user by email
-    const existing = await pool.query(
-      'SELECT id, username, email FROM users WHERE email = $1',
-      [email]
-    );
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
 
-    if (existing.rows.length > 0) {
-      const user = existing.rows[0];
-      // Update login_status
-      await pool.query('UPDATE users SET login_status = true WHERE id = $1', [user.id]);
-      return { userId: user.id, username: user.username, email: user.email, isNew: false };
-    }
-
-    // Check if username is taken
-    const usernameCheck = await pool.query(
-      'SELECT id FROM users WHERE username = $1',
-      [username]
+    const result = await pool.query(
+      `SELECT s.user_id, u.username, u.email
+       FROM app.user_sessions s
+       JOIN app.users u ON u.id = s.user_id
+       WHERE s.token_hash = $1
+         AND s.expires_at > NOW()
+         AND s.revoked_at IS NULL`,
+      [tokenHash]
     );
-    if (usernameCheck.rows.length > 0) {
-      throw new Error(`Username "${username}" is already taken. Try a different one.`);
-    }
 
-    // Create new user
-    const inserted = await pool.query(
-      'INSERT INTO users (username, email, login_status) VALUES ($1, $2, true) RETURNING id, username, email',
-      [username, email]
-    );
-    const newUser = inserted.rows[0];
-    return { userId: newUser.id, username: newUser.username, email: newUser.email, isNew: true };
+    if (result.rows.length === 0) return null;
+
+    const row = result.rows[0];
+    return {
+      userId: String(row.user_id),
+      username: row.username || 'unknown',
+      email: row.email || '',
+    };
   } finally {
     if (ownPool) await pool.end().catch(() => {});
   }
 }
 
 /**
- * Set login_status to false for the given user.
- * @param {string} userId  UUID
+ * Revoke a CLI session token (logout).
+ * @param {string} token  raw token
  * @param {object} [opts]          optional overrides for testing
- * @param {object} [opts.pool]     pg Pool instance (skips internal pool creation)
+ * @param {object} [opts.pool]     pg Pool instance
  */
-async function logoutUser(userId, opts) {
+async function revokeToken(token, opts) {
+  if (!token) return;
+
   const ownPool = !(opts && opts.pool);
   const pool = (opts && opts.pool) || new Pool(dbConfig);
   try {
-    await pool.query('UPDATE users SET login_status = false WHERE id = $1', [userId]);
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+    await pool.query(
+      'UPDATE app.user_sessions SET revoked_at = NOW() WHERE token_hash = $1',
+      [tokenHash]
+    );
   } finally {
     if (ownPool) await pool.end().catch(() => {});
   }
 }
 
-module.exports = { loginOrRegister, logoutUser };
+module.exports = { validateToken, revokeToken };

package/src/cli/commands/analyze.js

@@ -260,7 +260,7 @@ module.exports = async function analyzeCommand(target, flags) {
     // Only show spinner if user is logged in
     const { loadSession } = require('../../utils/config');
     const session = loadSession();
-    if (session.userId) {
+    if (session.token) {
       syncSpinner.start();
     }
 

package/src/cli/commands/login.js

@@ -1,68 +1,117 @@
 'use strict';
 
-const readline = require('readline');
+const http = require('http');
+const crypto = require('crypto');
 const pc = require('picocolors');
 const { saveSession, loadSession } = require('../../utils/config');
-const { loginOrRegister } = require('../../api/auth');
+
+const WEB_URL = 'https://weci-holic.hackathon.sev-2.com';
 
 /**
- * Prompt user for input (visible).
+ * Open a URL in the default browser (cross-platform).
  */
-function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
+function openBrowser(url) {
+  const { exec } = require('child_process');
+  const cmd = process.platform === 'win32' ? `start "" "${url}"`
+    : process.platform === 'darwin' ? `open "${url}"`
+    : `xdg-open "${url}"`;
+  exec(cmd);
 }
 
+/**
+ * Spawn a temporary local HTTP server, open the browser for GitHub OAuth,
+ * and wait for the web app to redirect the token back.
+ *
+ * Flow:
+ *  1. CLI starts local server on a random port
+ *  2. CLI opens browser to {WEB_URL}/cli-auth?code={CODE}&port={PORT}
+ *  3. User logs in with GitHub on the web app
+ *  4. Web app creates a session token and redirects to http://localhost:{PORT}/callback?token=...&username=...&email=...
+ *  5. CLI receives the token, saves session, and shuts down local server
+ */
 module.exports = async function loginCommand() {
   const session = loadSession();
-  if (session.userId) {
+  if (session.token) {
     console.log(pc.yellow(`Already logged in as ${session.username} (${session.email}).`));
     console.log(`Run ${pc.cyan('legacyver logout')} first to switch accounts.`);
     return;
   }
 
   console.log(pc.bold('\nLegacyver Login\n'));
-  console.log(pc.dim('Your account is used to sync generated docs to the cloud.'));
-  console.log(pc.dim('If you don\'t have an account, one will be created automatically.\n'));
+  console.log(pc.dim('Opening your browser to log in with GitHub...\n'));
 
-  const email = await prompt('  Email: ');
-  if (!email || !email.includes('@')) {
-    console.error(pc.red('Invalid email address.'));
-    process.exit(1);
-  }
+  const code = crypto.randomBytes(16).toString('hex');
 
-  const username = await prompt('  Username: ');
-  if (!username || username.length < 2) {
-    console.error(pc.red('Username must be at least 2 characters.'));
-    process.exit(1);
-  }
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost`);
+
+      if (url.pathname === '/callback') {
+        const token = url.searchParams.get('token');
+        const username = url.searchParams.get('username');
+        const email = url.searchParams.get('email');
+
+        if (token && username) {
+          // Save session with the token
+          saveSession({
+            token,
+            username,
+            email: email || '',
+          });
+
+          // Send a nice HTML response to the browser
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(`
+            <html>
+              <body style="background:#0a0a0a;color:#fff;font-family:monospace;display:flex;align-items:center;justify-content:center;height:100vh;margin:0">
+                <div style="text-align:center">
+                  <h1 style="color:#22c55e">Logged in!</h1>
+                  <p>You can close this tab and return to the CLI.</p>
+                </div>
+              </body>
+            </html>
+          `);
 
-  try {
-    const result = await loginOrRegister(email, username);
-    saveSession({
-      userId: result.userId,
-      username: result.username,
-      email: result.email,
+          console.log(pc.green(`  Logged in as ${username} (${email})`));
+          console.log(pc.dim('  Generated docs will now sync to the cloud after each analyze run.\n'));
+
+          // Shut down server after a short delay
+          setTimeout(() => {
+            server.close();
+            resolve();
+          }, 500);
+        } else {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end('Missing token or username in callback.');
+        }
+        return;
+      }
+
+      // Any other path
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not found');
     });
 
-    if (result.isNew) {
-      console.log(pc.green(`\n  Account created! Logged in as ${result.username} (${result.email})`));
-    } else {
-      console.log(pc.green(`\n  Logged in as ${result.username} (${result.email})`));
-    }
-    console.log(pc.dim('  Generated docs will now sync to the cloud after each analyze run.\n'));
-  } catch (err) {
-    if (err.message.includes('already taken')) {
-      console.error(pc.red(`\n  ${err.message}`));
-    } else {
-      console.error(pc.red(`\n  Login failed: ${err.message}`));
-      console.error(pc.dim('  Check your internet connection and try again.'));
-    }
-    process.exit(1);
-  }
+    // Listen on a random available port
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      const authUrl = `${WEB_URL}/cli-auth?code=${code}&port=${port}`;
+
+      console.log(pc.dim(`  Listening on http://localhost:${port}`));
+      console.log(pc.dim(`  If the browser doesn't open, visit:\n`));
+      console.log(`  ${pc.cyan(authUrl)}\n`);
+      console.log(pc.dim('  Waiting for authentication...\n'));
+
+      openBrowser(authUrl);
+    });
+
+    // Timeout after 5 minutes
+    const timeout = setTimeout(() => {
+      console.error(pc.red('\n  Login timed out. Please try again.'));
+      server.close();
+      reject(new Error('Login timed out'));
+    }, 5 * 60 * 1000);
+
+    server.on('close', () => clearTimeout(timeout));
+  });
 };

package/src/cli/commands/logout.js

@@ -2,17 +2,17 @@
 
 const pc = require('picocolors');
 const { loadSession, clearSession } = require('../../utils/config');
-const { logoutUser } = require('../../api/auth');
+const { revokeToken } = require('../../api/auth');
 
 module.exports = async function logoutCommand() {
   const session = loadSession();
-  if (!session.userId) {
+  if (!session.token) {
     console.log('You are not logged in.');
     return;
   }
 
   try {
-    await logoutUser(session.userId);
+    await revokeToken(session.token);
   } catch {
     // DB update failed — still clear local session
   }

package/src/cli/commands/providers.js

@@ -20,7 +20,7 @@ module.exports = async function providersCommand() {
   // ─── Legacyver Account ────────────────────────────────────────────────────
   const session = loadSession();
   console.log(pc.bold('\nLegacyver Account'));
-  if (session.userId) {
+  if (session.token) {
     console.log(`  ${pc.green('Logged in')} as ${session.username} (${session.email})`);
     console.log('  Generated docs will sync to the cloud after each analyze run.');
   } else {

package/src/cli/commands/push.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const pc = require('picocolors');
+const { loadSession } = require('../../utils/config');
+const logger = require('../../utils/logger');
+
+/**
+ * legacyver push [target]
+ *
+ * Manually push existing generated docs to the cloud database.
+ * Reads markdown files from the output directory (default: ./legacyver-docs)
+ * and pushes them as documentation pages.
+ *
+ * Useful when:
+ * - analyze ran but DB was down at that time
+ * - you want to re-push after fixing DB issues
+ * - you generated docs on a machine without login and want to push from another
+ */
+module.exports = async function pushCommand(target, options) {
+  const session = loadSession();
+  if (!session.token) {
+    console.log(pc.red('\n  Not logged in. Run ') + pc.cyan('legacyver login') + pc.red(' first.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const targetDir = path.resolve(target || '.');
+  const outDir = path.resolve(options.out || './legacyver-docs');
+
+  // Check if output directory exists
+  if (!fs.existsSync(outDir)) {
+    console.log(pc.red(`\n  Output directory not found: ${outDir}`));
+    console.log(pc.dim('  Run ') + pc.cyan('legacyver analyze') + pc.dim(' first to generate docs.\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Collect all .md files from the output directory
+  const fragments = [];
+  collectMarkdownFiles(outDir, outDir, fragments);
+
+  if (fragments.length === 0) {
+    console.log(pc.yellow('\n  No markdown files found in ') + pc.cyan(outDir));
+    console.log(pc.dim('  Run ') + pc.cyan('legacyver analyze') + pc.dim(' first to generate docs.\n'));
+    return;
+  }
+
+  console.log(pc.bold('\nLegacyver Push\n'));
+  console.log(pc.dim(`  Source:  ${targetDir}`));
+  console.log(pc.dim(`  Docs:   ${outDir}`));
+  console.log(pc.dim(`  Files:  ${fragments.length} markdown files\n`));
+
+  // Dynamically require ora for spinner
+  let spinner;
+  try {
+    const ora = require('ora');
+    spinner = ora('Pushing docs to cloud...').start();
+  } catch {
+    console.log('  Pushing docs to cloud...');
+    spinner = { succeed: (m) => console.log(pc.green('  ' + m)), fail: (m) => console.log(pc.red('  ' + m)) };
+  }
+
+  try {
+    const { pushToDatabase } = require('../../db/index');
+    const result = await pushToDatabase(fragments, targetDir);
+
+    if (result.skipped) {
+      spinner.fail('Push skipped — token may be invalid or expired. Try logging in again.');
+      process.exitCode = 1;
+    } else {
+      spinner.succeed(`Pushed ${result.pushed} files to cloud`);
+      console.log(pc.dim('\n  Docs are now visible on the web dashboard.\n'));
+    }
+  } catch (err) {
+    spinner.fail('Push failed: ' + err.message);
+    logger.error('Push error details:', err);
+    process.exitCode = 1;
+  }
+};
+
+/**
+ * Recursively collect .md files from a directory.
+ * Each file becomes a fragment with { relativePath, content }.
+ */
+function collectMarkdownFiles(baseDir, dir, results) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectMarkdownFiles(baseDir, fullPath, results);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const relativePath = path.relative(baseDir, fullPath);
+      const content = fs.readFileSync(fullPath, 'utf8');
+      results.push({ relativePath, content });
+    }
+  }
+}

package/src/cli/ui.js

@@ -84,7 +84,7 @@ function printSummary(stats) {
   // Show login tip if user is not logged in
   const { loadSession } = require('../utils/config');
   const session = loadSession();
-  if (!session.userId) {
+  if (!session.token) {
     console.log(pc.dim('─────────────────────────────────────────────────'));
     console.log(pc.cyan('  Sync docs to the cloud:'));
     console.log('');

package/src/db/index.js

@@ -4,6 +4,7 @@ const { Pool } = require('pg');
 const path = require('path');
 const dbConfig = require('./config');
 const { loadSession } = require('../utils/config');
+const { validateToken } = require('../api/auth');
 const logger = require('../utils/logger');
 
 let _pool = null;
@@ -21,7 +22,7 @@ function getPool() {
 /**
  * Find or create a repository for the given user + project path.
  * @param {Pool} pool
- * @param {string} userId  UUID
+ * @param {string} userId  app.users.id (BIGINT as string)
  * @param {string} projectPath  absolute path of the analyzed directory
  * @returns {Promise<string>} repository id (UUID)
  */
@@ -31,7 +32,7 @@ async function getOrCreateRepo(pool, userId, projectPath) {
 
   // Try find existing
   const existing = await pool.query(
-    'SELECT id FROM repositories WHERE user_id = $1 AND full_name = $2',
+    'SELECT id FROM app.repositories WHERE user_id = $1 AND full_name = $2',
     [userId, fullName]
   );
   if (existing.rows.length > 0) {
@@ -40,7 +41,7 @@ async function getOrCreateRepo(pool, userId, projectPath) {
 
   // Insert new
   const inserted = await pool.query(
-    'INSERT INTO repositories (user_id, name, full_name) VALUES ($1, $2, $3) RETURNING id',
+    'INSERT INTO app.repositories (user_id, name, full_name) VALUES ($1, $2, $3) RETURNING id',
     [userId, name, fullName]
   );
   return inserted.rows[0].id;
@@ -56,7 +57,7 @@ async function getOrCreateRepo(pool, userId, projectPath) {
  */
 async function getOrCreateDocumentation(pool, repositoryId, repoName) {
   const existing = await pool.query(
-    'SELECT id FROM documentations WHERE repository_id = $1',
+    'SELECT id FROM app.documentations WHERE repository_id = $1',
     [repositoryId]
   );
   if (existing.rows.length > 0) {
@@ -64,7 +65,7 @@ async function getOrCreateDocumentation(pool, repositoryId, repoName) {
   }
 
   const inserted = await pool.query(
-    'INSERT INTO documentations (repository_id, title, description) VALUES ($1, $2, $3) RETURNING id',
+    'INSERT INTO app.documentations (repository_id, title, description) VALUES ($1, $2, $3) RETURNING id',
     [repositoryId, `${repoName} Documentation`, `Auto-generated documentation for ${repoName}`]
   );
   return inserted.rows[0].id;
@@ -88,20 +89,20 @@ async function upsertPages(pool, documentationId, fragments) {
 
     // Check if page exists
     const existing = await pool.query(
-      'SELECT id FROM documentation_pages WHERE documentation_id = $1 AND slug = $2',
+      'SELECT id FROM app.documentation_pages WHERE documentation_id = $1 AND slug = $2',
       [documentationId, slug]
     );
 
     if (existing.rows.length > 0) {
       // Update existing
       await pool.query(
-        'UPDATE documentation_pages SET content = $1, title = $2, page_order = $3, created_at = NOW() WHERE id = $4',
+        'UPDATE app.documentation_pages SET content = $1, title = $2, page_order = $3, created_at = NOW() WHERE id = $4',
         [frag.content, title, i + 1, existing.rows[0].id]
       );
     } else {
       // Insert new
       await pool.query(
-        'INSERT INTO documentation_pages (documentation_id, slug, title, content, page_order) VALUES ($1, $2, $3, $4, $5)',
+        'INSERT INTO app.documentation_pages (documentation_id, slug, title, content, page_order) VALUES ($1, $2, $3, $4, $5)',
         [documentationId, slug, title, frag.content, i + 1]
       );
     }
@@ -112,25 +113,36 @@ async function upsertPages(pool, documentationId, fragments) {
 
 /**
  * Top-level push function. Called from analyze command.
- * Short-circuits if user is not logged in.
+ * Validates the CLI token, then pushes docs to DB.
+ * Short-circuits if user is not logged in or token is invalid.
  * @param {Array<{relativePath: string, content: string}>} fragments
  * @param {string} projectPath  absolute path of the analyzed directory
  * @param {object} [opts]          optional overrides for testing
  * @param {object} [opts.pool]     pg Pool instance (skips singleton pool)
  * @param {object} [opts.session]  session object (skips loadSession)
+ * @param {object} [opts.user]     user object (skips validateToken) — { userId, username, email }
  * @returns {Promise<{skipped: boolean, pushed?: number}>}
  */
 async function pushToDatabase(fragments, projectPath, opts) {
   const session = (opts && opts.session) || loadSession();
-  if (!session.userId) {
+  if (!session.token) {
     return { skipped: true };
   }
 
+  // Validate the token to get user info
+  let user = (opts && opts.user) || null;
+  if (!user) {
+    user = await validateToken(session.token);
+    if (!user) {
+      return { skipped: true };
+    }
+  }
+
   const ownPool = !(opts && opts.pool);
   const pool = (opts && opts.pool) || getPool();
   try {
     const repoName = path.basename(projectPath);
-    const repoId = await getOrCreateRepo(pool, session.userId, projectPath);
+    const repoId = await getOrCreateRepo(pool, user.userId, projectPath);
     const docId = await getOrCreateDocumentation(pool, repoId, repoName);
     const pushed = await upsertPages(pool, docId, fragments);
     return { skipped: false, pushed };