ngx-git 1.0.0

package/cli.js

@@ -0,0 +1,643 @@
+#!/usr/bin/env node
+
+/**
+ * NGX CLI v4.0
+ * Pushes code directly to your GitHub repos via NGX server (OAuth proxy).
+ * No git installation needed. No commit setup. No branch config.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const http = require("http");
+const os = require("os");
+
+const axios = require("axios");
+
+const _log = console.log;
+console.log = () => {};
+require("dotenv").config();
+console.log = _log;
+
+const VERSION = "4.0.0";
+const CONFIG_PATH = path.join(os.homedir(), ".ngxconfig");
+const CB_PORT = 9988; // local callback server port for OAuth
+
+const encoded = atob("aHR0cHM6Ly9uZ3gubmdpbnhzb2Z0Lm9ubGluZS9hcGk=");
+// console.log(encoded);
+// ─── Default ignore patterns ──────────────────────────────────────────────────
+const DEFAULT_IGNORE = new Set([
+  ".env",
+  "node_modules",
+  ".git",
+  ".DS_Store",
+  "Thumbs.db",
+  "dist",
+  "build",
+  ".cache",
+  "coverage",
+  ".nyc_output",
+  "tmp",
+  "temp",
+  "__pycache__",
+  ".pytest_cache",
+  ".mypy_cache",
+  "*.log",
+  "*.sqlite",
+  "*.db",
+  "*.pem",
+  "*.key",
+  "*.p12",
+  "*.pfx",
+  "*.cer",
+  "*.crt",
+  "secrets",
+  ".secrets",
+]);
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+function cfg() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveCfg(d) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(d, null, 2));
+}
+
+function getServer() {
+  return cfg().server || process.env.NGX_SERVER || encoded;
+}
+function getToken() {
+  return cfg().token || process.env.NGX_TOKEN || null;
+}
+function getUsername() {
+  return cfg().username || null;
+}
+function authHdr() {
+  const t = getToken();
+  if (!t) fatal("Not logged in. Run:  ngx login");
+  return { Authorization: `Bearer ${t}`, "Content-Type": "application/json" };
+}
+
+// ─── Output ───────────────────────────────────────────────────────────────────
+const C = {
+  cyan: (s) => `\x1b[96m${s}\x1b[0m`,
+  green: (s) => `\x1b[92m${s}\x1b[0m`,
+  grey: (s) => `\x1b[90m${s}\x1b[0m`,
+  red: (s) => `\x1b[91m${s}\x1b[0m`,
+  yel: (s) => `\x1b[93m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+function fatal(msg) {
+  console.error(C.red("✗ ") + msg);
+  process.exit(1);
+}
+function ok(msg) {
+  console.log(C.green("✓ ") + msg);
+}
+function info(msg) {
+  console.log(C.grey("  ") + msg);
+}
+function step(msg) {
+  process.stdout.write(`\r${C.cyan("›")} ${msg}                    `);
+}
+
+// ─── Ignore logic ─────────────────────────────────────────────────────────────
+function loadIgnorePatterns(folderPath) {
+  const pats = new Set(DEFAULT_IGNORE);
+  // Read .ngxignore
+  const ngxFile = path.join(folderPath, ".ngxignore");
+  if (fs.existsSync(ngxFile))
+    fs.readFileSync(ngxFile, "utf-8")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#"))
+      .forEach((p) => pats.add(p));
+  // Read .gitignore
+  const gitFile = path.join(folderPath, ".gitignore");
+  if (fs.existsSync(gitFile))
+    fs.readFileSync(gitFile, "utf-8")
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#"))
+      .forEach((p) => pats.add(p));
+  return pats;
+}
+
+function matchesIgnore(name, patterns) {
+  for (const p of patterns) {
+    if (p === name) return true;
+    if (p.startsWith("*.") && name.endsWith(p.slice(1))) return true;
+    if (p.endsWith("*") && name.startsWith(p.slice(0, -1))) return true;
+    if (p.startsWith("*") && name.endsWith(p.slice(1))) return true;
+  }
+  return false;
+}
+
+// ─── Collect files from folder ────────────────────────────────────────────────
+// Returns array of { path: "relative/path", content_b64: "..." }
+function collectFiles(folderPath) {
+  const ignore = loadIgnorePatterns(folderPath);
+  const files = [];
+
+  function walk(dir, rel) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (matchesIgnore(entry.name, ignore)) continue;
+      const fullPath = path.join(dir, entry.name);
+      const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (entry.isFile()) {
+        const buf = fs.readFileSync(fullPath);
+        // Skip binary files > 50 MB (GitHub limit)
+        if (buf.length > 50 * 1024 * 1024) {
+          console.log(
+            C.yel(
+              `  ⚠ Skipping large file: ${relPath} (${(buf.length / 1024 / 1024).toFixed(1)} MB)`,
+            ),
+          );
+          continue;
+        }
+        files.push({ path: relPath, content_b64: buf.toString("base64") });
+      }
+    }
+  }
+  walk(folderPath, "");
+  return files;
+}
+
+// ─── LOGIN — GitHub OAuth ─────────────────────────────────────────────────────
+async function doLogin() {
+  const existing = getToken();
+  if (existing) {
+    ok(`Already logged in as ${C.bold(getUsername())}`);
+    info("Run 'ngx logout' to switch accounts.");
+    return;
+  }
+
+  console.log(`\n${C.bold("NGX GitHub Login")}`);
+
+  const loginUrl = `${getServer()}/auth/github`;
+  console.log(C.grey(`Opening: ${loginUrl}\n`));
+
+  // Try to open browser
+  try {
+    const { default: open } = await import("open").catch(() => ({
+      default: null,
+    }));
+    if (open) await open(loginUrl);
+    else console.log(C.yel(`Open this in your browser:\n  ${loginUrl}\n`));
+  } catch {
+    console.log(C.yel(`Open this in your browser:\n  ${loginUrl}\n`));
+  }
+
+  // Spin local HTTP server to receive token
+  return new Promise((resolve, reject) => {
+    const srv = http.createServer((req, res) => {
+      const CORS = {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Headers": "Content-Type",
+      };
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, CORS);
+        res.end();
+        return;
+      }
+      if (req.method === "POST" && req.url === "/token") {
+        let body = "";
+        req.on("data", (d) => (body += d));
+        req.on("end", () => {
+          res.writeHead(200, { "Content-Type": "application/json", ...CORS });
+          res.end(JSON.stringify({ ok: true }));
+          try {
+            const { token, username } = JSON.parse(body);
+            const c = cfg();
+            c.token = token;
+            c.username = username;
+            saveCfg(c);
+            srv.close();
+            console.log();
+            ok(`Logged in as ${C.bold(username)}`);
+            resolve();
+          } catch (e) {
+            reject(e);
+          }
+        });
+      } else {
+        res.writeHead(404, CORS);
+        res.end();
+      }
+    });
+
+    srv.on("error", (e) => {
+      if (e.code === "EADDRINUSE")
+        fatal(
+          `Port ${CB_PORT} is busy. Kill whatever is using it and try again.`,
+        );
+      reject(e);
+    });
+
+    srv.listen(CB_PORT, () =>
+      info(`Waiting for GitHub callback (port ${CB_PORT})...`),
+    );
+    setTimeout(() => {
+      srv.close();
+      fatal("Login timed out (5 min).");
+    }, 300_000);
+  });
+}
+
+// ─── PUSH — upload files to GitHub via server ────────────────────────────────
+async function doPush(repoArg, opts = {}) {
+  const username = getUsername();
+  if (!username) fatal("Not logged in. Run: ngx login");
+  const server = getServer();
+  const folder = path.resolve(opts.path || ".");
+  if (!fs.existsSync(folder)) fatal(`Folder not found: ${folder}`);
+
+  const repoName = repoArg || path.basename(folder);
+  const isPrivate = opts.visibility !== "public";
+  const commitMsg = opts.message || `ngx push — ${new Date().toLocaleString()}`;
+  const branch = opts.branch || "main";
+
+  step(`Scanning ${C.bold(folder)}...`);
+  const files = collectFiles(folder);
+  if (!files.length) fatal("No files found to push (everything was ignored).");
+  process.stdout.write(`\n`);
+
+  // Show summary
+  const totalKB =
+    files.reduce((s, f) => s + Buffer.from(f.content_b64, "base64").length, 0) /
+    1024;
+  info(
+    `${files.length} files  •  ${totalKB.toFixed(1)} KB  →  ${C.bold(username + "/" + repoName)}`,
+  );
+
+  step("Pushing to GitHub...");
+  try {
+    const res = await axios.post(
+      `${server}/push`,
+      {
+        repoName,
+        files,
+        message: commitMsg,
+        branch,
+        createIfMissing: true,
+        private: isPrivate,
+      },
+      { headers: authHdr(), maxBodyLength: Infinity, timeout: 120_000 },
+    );
+
+    process.stdout.write("\n");
+    ok(`Pushed ${C.bold(res.data.files)} files to ${C.bold(res.data.repo)}`);
+    info(`Branch : ${res.data.branch}`);
+    info(`Commit : ${res.data.commit}`);
+    info(`GitHub : ${C.cyan(res.data.url)}`);
+  } catch (e) {
+    process.stdout.write("\n");
+    fatal(e.response?.data?.error || e.message);
+  }
+}
+
+// ─── CLONE — clone repo from GitHub ──────────────────────────────────────────
+// Uses GitHub API to fetch file tree + blob contents, writes to disk.
+// No `git` binary needed.
+async function doClone(target, destArg, opts = {}) {
+  if (!target || !target.includes("/"))
+    fatal("Usage: ngx clone owner/repo [dest]");
+  const [owner, repoName] = target.split("/");
+  const dest = path.resolve(destArg || repoName);
+  const server = getServer();
+
+  step(`Fetching file tree for ${C.bold(target)}...`);
+  let treeData;
+  try {
+    const res = await axios.get(`${server}/tree/${owner}/${repoName}`, {
+      headers: authHdr(),
+    });
+    treeData = res.data;
+  } catch (e) {
+    process.stdout.write("\n");
+    if (e.response?.status === 404)
+      fatal("Repo not found or you don't have access");
+    fatal(e.response?.data?.error || e.message);
+  }
+
+  const files = treeData.files || [];
+  const branch = treeData.branch;
+  process.stdout.write("\n");
+  info(`${files.length} files on branch ${branch}`);
+
+  // GitHub raw content URL for each file
+  const ghToken = null; // optional: could expose via /me route
+  const ghHeaders = { Accept: "application/vnd.github.raw+json", ...authHdr() };
+  // We'll download via the server proxy or directly from GitHub raw
+  const repoInfo = await axios.get(`${server}/repos/${owner}/${repoName}`, {
+    headers: authHdr(),
+  });
+  const cloneBase = `https://raw.githubusercontent.com/${owner}/${repoName}/${branch}`;
+
+  // For private repos we need the GitHub token — fetch it via server
+  let rawHeaders = {};
+  try {
+    // The server can expose a /me/ghtoken route for the logged-in user's own repos
+    const tk = await axios.get(`${server}/me/ghtoken`, { headers: authHdr() });
+    if (tk.data?.ghToken)
+      rawHeaders["Authorization"] = `Bearer ${tk.data.ghToken}`;
+  } catch {}
+
+  if (fs.existsSync(dest)) {
+    info(`Destination ./${path.basename(dest)}/ already exists — overwriting`);
+  } else {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  let done = 0;
+  for (const file of files) {
+    step(`Downloading ${done + 1}/${files.length}  ${C.grey(file.path)}`);
+    try {
+      const raw = await axios.get(`${cloneBase}/${file.path}`, {
+        headers: rawHeaders,
+        responseType: "arraybuffer",
+      });
+      const outPath = path.join(dest, file.path);
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      fs.writeFileSync(outPath, raw.data);
+      done++;
+    } catch (e) {
+      process.stdout.write("\n");
+      info(
+        C.yel(
+          `Could not download: ${file.path} — ${e.response?.status || e.message}`,
+        ),
+      );
+    }
+  }
+  process.stdout.write("\n");
+  ok(
+    `Cloned ${C.bold(target)} (${done}/${files.length} files) → ./${path.basename(dest)}/`,
+  );
+}
+
+// ─── REPOS ────────────────────────────────────────────────────────────────────
+async function listRepos() {
+  if (!getToken()) fatal("Not logged in");
+  step("Fetching repos from GitHub...");
+  try {
+    const res = await axios.get(`${getServer()}/repos`, { headers: authHdr() });
+    process.stdout.write("\n");
+    const repos = res.data.repos || [];
+    if (!repos.length) {
+      info("No repos found.");
+      return;
+    }
+    console.log(`\n${C.bold(getUsername() + "'s GitHub repos:")}\n`);
+    repos.forEach((r) => {
+      const icon = r.private ? "🔒" : "🌐";
+      const lang = r.language ? C.grey(r.language.padEnd(14)) : " ".repeat(14);
+      const upd = r.pushed_at ? timeSince(r.pushed_at) : "—";
+      console.log(
+        `  ${icon} ${C.cyan(r.name.padEnd(32))} ${lang} ${C.grey(upd)}`,
+      );
+    });
+    console.log();
+  } catch (e) {
+    process.stdout.write("\n");
+    fatal(e.response?.data?.error || e.message);
+  }
+}
+
+// ─── CREATE REPO ──────────────────────────────────────────────────────────────
+async function createRepo(name, opts = {}) {
+  if (!name) fatal('Usage: ngx create <reponame> [--public] [--desc "..."]');
+  step(`Creating ${C.bold(name)} on GitHub...`);
+  try {
+    const res = await axios.post(
+      `${getServer()}/repos`,
+      {
+        name,
+        private: opts.visibility !== "public",
+        description: opts.desc || "",
+      },
+      { headers: authHdr() },
+    );
+    process.stdout.write("\n");
+    ok(`Created ${C.bold(res.data.full_name)}`);
+    info(`GitHub : ${C.cyan(`https://github.com/${res.data.full_name}`)}`);
+    info(`Private: ${res.data.private}`);
+  } catch (e) {
+    process.stdout.write("\n");
+    fatal(e.response?.data?.error || e.message);
+  }
+}
+
+// ─── DELETE ───────────────────────────────────────────────────────────────────
+async function deleteRepo(name) {
+  if (!name) fatal("Usage: ngx delete <reponame>");
+  step(`Deleting ${C.bold(name)}...`);
+  try {
+    const res = await axios.delete(`${getServer()}/repos/${name}`, {
+      headers: authHdr(),
+    });
+    process.stdout.write("\n");
+    ok(res.data.message);
+  } catch (e) {
+    process.stdout.write("\n");
+    fatal(e.response?.data?.error || e.message);
+  }
+}
+
+// ─── VISIBILITY ───────────────────────────────────────────────────────────────
+async function setVisibility(name, vis) {
+  if (!name || !["public", "private"].includes(vis))
+    fatal("Usage: ngx visibility <repo> public|private");
+  try {
+    const res = await axios.patch(
+      `${getServer()}/repos/${name}/visibility`,
+      { visibility: vis },
+      { headers: authHdr() },
+    );
+    ok(res.data.message);
+  } catch (e) {
+    fatal(e.response?.data?.error || e.message);
+  }
+}
+
+// ─── LOGS ─────────────────────────────────────────────────────────────────────
+async function showLogs() {
+  if (!getToken()) fatal("Not logged in");
+  try {
+    const res = await axios.get(`${getServer()}/logs`, { headers: authHdr() });
+    const logs = res.data.logs || [];
+    if (!logs.length) {
+      info("No activity yet.");
+      return;
+    }
+    console.log();
+    logs.forEach((l) => {
+      const ts = new Date(l.ts).toLocaleString();
+      const det =
+        l.details && Object.keys(l.details).length
+          ? C.grey(" " + JSON.stringify(l.details))
+          : "";
+      console.log(
+        `  ${C.grey(ts)}  ${C.cyan(l.action.padEnd(18))}  ${l.repo || ""}${det}`,
+      );
+    });
+    console.log();
+  } catch (e) {
+    fatal(e.response?.data?.error || e.message);
+  }
+}
+
+// ─── UTILS ────────────────────────────────────────────────────────────────────
+function timeSince(d) {
+  const s = Math.floor((Date.now() - new Date(d)) / 1000);
+  if (s < 60) return "just now";
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+function parseArgs(rawArgs) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i].startsWith("--")) {
+      const key = rawArgs[i].slice(2);
+      const val =
+        rawArgs[i + 1] && !rawArgs[i + 1].startsWith("--")
+          ? rawArgs[++i]
+          : true;
+      flags[key] = val;
+    } else {
+      rest.push(rawArgs[i]);
+    }
+  }
+  return { flags, rest };
+}
+
+// ─── MAIN ─────────────────────────────────────────────────────────────────────
+const [, , cmd, ...rawArgs] = process.argv;
+const { flags, rest } = parseArgs(rawArgs || []);
+
+(async () => {
+  switch (cmd) {
+    case "-v":
+    case "--version":
+      console.log(`ngx ${VERSION}`);
+      break;
+
+    case "login":
+      await doLogin();
+      break;
+
+    case "logout":
+      const c2 = cfg();
+      delete c2.token;
+      delete c2.username;
+      saveCfg(c2);
+      ok("Logged out");
+      break;
+
+    case "whoami":
+      const u = getUsername();
+      if (u) console.log(`Logged in as: ${C.bold(u)}  (${getServer()})`);
+      else console.log("Not logged in");
+      break;
+
+    // ngx push [reponame] [--path <dir>] [--public] [--message "msg"] [--branch main]
+    case "push":
+      await doPush(rest[0], {
+        path: flags.path,
+        visibility: flags.public ? "public" : flags.visibility || "private",
+        message: flags.message || flags.m,
+        branch: flags.branch || flags.b,
+      });
+      break;
+
+    // ngx clone owner/repo [dest]
+    case "clone":
+      if (!rest[0]) fatal("Usage: ngx clone owner/repo [dest]");
+      await doClone(rest[0], rest[1], {});
+      break;
+
+    // ngx repos
+    case "repos":
+      await listRepos();
+      break;
+
+    // ngx create <name> [--public] [--desc "..."]
+    case "create":
+      await createRepo(rest[0], {
+        visibility: flags.public ? "public" : "private",
+        desc: flags.desc || flags.description || "",
+      });
+      break;
+
+    // ngx delete <name>
+    case "delete":
+      if (!rest[0]) fatal("Usage: ngx delete <reponame>");
+      await deleteRepo(rest[0]);
+      break;
+
+    // ngx visibility <repo> public|private
+    case "visibility":
+      await setVisibility(rest[0], rest[1]);
+      break;
+
+    // ngx logs
+    case "logs":
+      await showLogs();
+      break;
+
+    // ngx config server <url>
+    case "config":
+      if (rest[0] === "server" && rest[1]) {
+        const c3 = cfg();
+        c3.server = rest[1];
+        saveCfg(c3);
+        ok(`Server set to ${rest[1]}`);
+      } else console.log("Usage: ngx config server <url>");
+      break;
+
+    default:
+      console.log(`
+${C.bold("NGX v" + VERSION)} — GitHub proxy CLI
+
+${C.cyan("Auth:")}
+  ngx login                              GitHub OAuth (opens browser)
+  ngx logout                             Clear saved session
+  ngx whoami                             Show current user
+
+${C.cyan("Push / Clone:")}
+  ngx push                               Push current folder to GitHub
+  ngx push my-repo                       Push with specific repo name
+  ngx push my-repo --public              Push as public repo
+  ngx push my-repo --path ./src          Push a subfolder
+  ngx push my-repo --message "feat: x"   Custom commit message
+  ngx clone owner/repo                   Clone repo (downloads all files)
+  ngx clone owner/repo ./local-dir       Clone into specific directory
+
+${C.cyan("Repos:")}
+  ngx repos                              List your GitHub repos
+  ngx create <name> [--public]           Create a new GitHub repo
+  ngx delete <name>                      Delete a GitHub repo
+  ngx visibility <repo> public|private   Change repo visibility
+
+${C.cyan("Logs:")}
+  ngx logs                               Your NGX activity log
+
+${C.cyan("Config:")}
+  ngx config server <url>                Point to a different NGX server
+  ngx -v                                 Show version
+
+${C.grey("Auto-ignored on push:")}
+  ${C.grey(".env  node_modules  .git  dist  build  *.key  *.pem  secrets")}
+  ${C.grey("Add extras in .ngxignore or .gitignore")}
+`);
+  }
+})();

package/data/test.txt

@@ -0,0 +1 @@
+how are 

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ngx-git",
+  "version": "1.0.0",
+  "description": "NGX - Minimal GitHub-like server",
+  "main": "server.js",
+  "bin": {
+    "ngx": "./cli.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "dev": "nodemon server.js"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.0.3",
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.2",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.1"
+  }
+}

package/readmi.txt

@@ -0,0 +1,189 @@
+# NGX v2.0 — Minimal GitHub-like Code Vault
+
+A self-hosted, lightweight code repository server with JWT auth, repo tokens, public/private repos, activity logging, and a React UI.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install dependencies
+```bash
+npm install
+```
+
+### 2. Configure environment
+```bash
+cp .env.example .env
+# Edit .env: set a strong JWT_SECRET
+```
+
+### 3. Start the server
+```bash
+npm start
+# Server runs at http://localhost:3000
+```
+
+### 4. Open the UI
+Open `ui.html` in your browser (or serve it via any static server).
+
+### 5. Install CLI globally
+```bash
+npm link
+# Now you can use `ngx` anywhere
+```
+
+---
+
+## 📡 Server API
+
+| Method | Route | Auth | Description |
+|--------|-------|------|-------------|
+| GET | `/status` | None | Server health check |
+| POST | `/auth/register` | None | Create account |
+| POST | `/auth/login` | None | Login, get JWT |
+| GET | `/repos/:user` | Optional | List repos (private filtered) |
+| GET | `/repos/:user/:repo` | Optional | Get repo info |
+| POST | `/repos/:user/:repo` | JWT | Create repo |
+| PATCH | `/repos/:user/:repo/visibility` | JWT | Toggle public/private |
+| DELETE | `/repos/:user/:repo` | JWT | Delete repo |
+| GET | `/repos/:user/:repo/token` | JWT | Get repo token |
+| POST | `/repos/:user/:repo/token/regenerate` | JWT | Regenerate token |
+| POST | `/push/:user/:repo` | JWT or Repo Token | Push zip |
+| GET | `/clone/:user/:repo` | None (public) / JWT or Repo Token (private) | Download zip |
+| GET | `/logs/:user` | JWT | Your activity log |
+| GET | `/logs/:user/:repo` | JWT (private) / None (public) | Repo activity |
+
+---
+
+## 🖥 CLI Commands
+
+### Auth
+```bash
+ngx register <username> <password>    # Register
+ngx login <username> <password>       # Login (saves JWT to ~/.ngxconfig)
+ngx logout                            # Clear session
+ngx whoami                            # Show current user
+```
+
+### Repo Management
+```bash
+ngx init <reponame> [public|private]  # Create a repo (default: private)
+ngx repos                             # List your repos
+ngx delete <reponame>                 # Delete (asks confirmation)
+ngx visibility <reponame> public      # Make public
+ngx visibility <reponame> private     # Make private
+```
+
+### Push / Clone
+```bash
+# Push (using JWT — must be logged in)
+ngx push ./my-project
+
+# Push (using repo token — no login needed)
+ngx push ./my-project --token <repo-token>
+
+# Clone public repo (no auth)
+ngx clone alice/my-project
+
+# Clone private repo (JWT must be logged in as owner)
+ngx clone alice/my-project
+
+# Clone private repo (using repo token)
+ngx clone alice/my-project --token <repo-token>
+
+# Clone into specific folder
+ngx clone alice/my-project ./local-copy
+```
+
+> **Note:** `push` and `clone` use the folder/repo name automatically.  
+> `.ngxsafe`, `node_modules`, and `.git` are excluded from push.
+
+### Tokens
+```bash
+ngx token show <reponame>    # Show current repo token
+ngx token regen <reponame>   # Regenerate (old token immediately invalid)
+```
+
+### Logs
+```bash
+ngx logs                     # Your last 100 actions
+ngx logs <reponame>          # Activity for a specific repo
+```
+
+### Server Config
+```bash
+ngx config server http://my-server.com:3000   # Point CLI to custom server
+ngx -v                                         # Show version
+```
+
+---
+
+## 🔐 Auth System
+
+### JWT (for UI and CLI login sessions)
+- Expires in **7 days**
+- Stored in `~/.ngxconfig` (CLI) or `sessionStorage` (UI)
+- Required for: creating repos, deleting, changing visibility, viewing tokens
+
+### Repo Token (for CI/CD, scripts, team sharing)
+- A UUID generated when repo is created
+- Does **not** expire unless regenerated
+- Can be used with `--token` flag in CLI
+- For **private repos**: needed by anyone who isn't the owner
+- For **public repos**: not needed for clone; needed for push
+
+### Public vs Private
+| Operation | Public Repo | Private Repo |
+|-----------|-------------|--------------|
+| Clone | Anyone, no auth | Owner JWT or Repo Token |
+| Push | Owner JWT or Repo Token | Owner JWT or Repo Token |
+| View info | Anyone | Owner only |
+
+---
+
+## 📁 File Structure
+
+```
+ngx-server/
+├── server.js        # Express API server
+├── cli.js           # CLI tool
+├── ui.html          # React UI (single file)
+├── package.json
+├── .env             # Your config (JWT_SECRET, PORT)
+├── .env.example
+├── data.json        # Users + repos DB (auto-created)
+├── activity.log     # Activity log (auto-created, NDJSON)
+├── repos/           # Stored zips (auto-created)
+│   └── <username>/
+│       └── <reponame>/
+│           └── latest.zip
+└── tmp/             # Upload temp dir (auto-created)
+```
+
+---
+
+## 🛡 Security Notes
+
+1. **Change `JWT_SECRET`** in `.env` before deploying — use a long random string.
+2. The `data.json` contains hashed passwords (bcrypt, 10 rounds). Never expose it publicly.
+3. For production, put HTTPS in front (nginx/caddy recommended).
+4. Consider adding rate limiting (e.g., `express-rate-limit`) for public deployments.
+5. Repo tokens are UUIDs — treat them like passwords.
+
+---
+
+## 🔧 Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| express | HTTP server |
+| multer | File upload handling |
+| jsonwebtoken | JWT sign/verify |
+| bcryptjs | Password hashing |
+| uuid | Repo token generation |
+| cors | Cross-origin requests |
+| adm-zip | Zip/unzip for push/clone |
+| axios | HTTP client (CLI) |
+| form-data | Multipart form (CLI) |
+| cross-spawn | Process spawning |
+| dotenv | Environment config |