qtex 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+Fair Source License, version 0.9
+
+Copyright © 2026 Sergio Lázaro
+
+1.  Grant. The Licensor grants you a non-exclusive, worldwide, royalty-free,
+    non-transferable, non-sublicensable license to use, copy, modify, and
+    distribute this Software in source code or binary form for any purpose,
+    subject to the following conditions:
+
+2.  Conditions.
+
+    a.  Redistribution. You must include this license and the copyright notice
+        above in all copies of the Software.
+
+    b.  Usage Limit. Use of the Software by a single legal entity (including its
+        affiliates) is limited to 3 concurrent users.
+
+3.  Commercial License. To use the Software beyond the Usage Limit, you must
+    obtain a separate commercial license from the Licensor at:
+    https://github.com/srsergiolazaro/vortex
+
+4.  Disclaimer. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED. THE LICENSOR SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES,
+    OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE.

package/README.md

@@ -0,0 +1,107 @@
+# 🌀 qtex CLI
+
+<p align="center">
+  <img src="docs/assets/banner.png" alt="Vortex Banner" width="600px">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/qtex"><img src="https://img.shields.io/npm/v/qtex?style=for-the-badge&logo=npm" alt="NPM Version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Fair_Source-blue.svg?style=for-the-badge" alt="License: Fair Source"></a>
+  <a href="https://latex.taptapp.xyz"><img src="https://img.shields.io/badge/Engine-Tectonic-blueviolet?style=for-the-badge&logo=rust" alt="Tachyon-Tex Engine"></a>
+  <a href="https://latex.taptapp.xyz"><img src="https://img.shields.io/badge/Latency-%3C1s-green?style=for-the-badge" alt="Real-time Latency"></a>
+</p>
+
+---
+
+**qtex CLI** is an ultra-fast, cloud-powered LaTeX compiler designed for developers who value speed and simplicity. Say goodbye to heavy local TeX distributions like TeXLive or MikTeX. Compile your documents in the cloud with sub-second latency and real-time feedback.
+
+---
+
+## 🚀 Key Features
+
+*   **⚡ Lightning Fast**: Powered by the Rust-based Tectonic engine, optimized for "moonshot" speed.
+*   **📦 Zero-Config**: No local dependencies required. Just run and compile.
+*   **👀 Smart Watch Mode**: Automatically detects changes in `.tex`, `.bib`, `.sty`, and even **images** (`.png`, `.jpg`, `.jpeg`) to recompile in milliseconds.
+*   **🔍 Intelligent Validation**: Pre-flight checks on the API to catch syntax errors before the full compilation process.
+*   **📂 Recursive Project Support**: Handles complex multi-file projects, including nested asset folders.
+
+---
+
+## 🧠 How it Works
+
+<p align="center">
+  <img src="docs/assets/flow.png" alt="qtex Workflow" width="700px">
+</p>
+
+1.  **Local Scan**: qtex recursively discovers all required assets (TeX, styles, images) in your project.
+2.  **Pre-flight Audit**: Sends a lightweight version to the `/validate` endpoint for immediate syntax feedback.
+3.  **Cloud Compilation**: Ships project files via high-speed multipart streams to the **Tachyon-Tex** cloud infrastructure.
+4.  **Instant Sync**: Downloads and saves the resulting PDF locally, reflecting changes almost instantly.
+
+---
+
+## 📦 Installation
+
+Install the CLI globally via NPM:
+
+```bash
+npm install -g qtex
+```
+
+*(Alternatively, you can clone and link it manually)*
+
+```bash
+git clone https://github.com/srsergiolazaro/qtex.git
+cd qtex
+npm install
+npm link
+```
+
+---
+
+## 🛠️ Usage
+
+### Quick Start
+Compile the folder containing your root LaTeX file:
+
+```bash
+qtex ./my-project
+```
+
+### Custom Output
+Define a specific filename for your generated PDF:
+
+```bash
+qtex ./my-project --output thesis_final.pdf
+```
+
+### Development (Live Recompilation)
+The `--watch` flag monitors your directory and recompiles instantly on any save:
+
+```bash
+qtex ./my-project --watch
+```
+
+---
+
+## 📡 Infrastructure & API
+
+qtex serves as the official CLI client for the **Tachyon-Tex** infrastructure:
+
+*   **Endpoint**: `https://latex.taptapp.xyz`
+*   **Engine**: Tectonic (Rust / XeTeX)
+*   **Privacy**: Stateless and ephemeral. Project data is processed in-memory and never stored.
+
+---
+
+## ⚖️ License
+
+This project is licensed under the **Fair Source License**.
+*   **Individual/Small Teams**: Free to use for individuals and organizations with up to 3 concurrent users.
+*   **Enterprise/Large Scale**: For use beyond 3 users, please contact us for a commercial license.
+
+For more details, see the [LICENSE](./LICENSE) file.
+
+---
+
+Built with ❤️ by the **Tachyon-Tex** team. Optimized for modern LaTeX workflows.

package/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import { watch } from 'node:fs';
+import { resolve, basename, extname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { colors, ui } from './src/ui.js';
+import { compile } from './src/compiler.js';
+
+// --- Entry Point ---
+const args = process.argv.slice(2);
+
+const optionsSchema = {
+    watch: { type: 'boolean', short: 'w' },
+    output: { type: 'string', short: 'o' },
+    help: { type: 'boolean', short: 'h' }
+};
+
+async function main() {
+    try {
+        const { values, positionals } = parseArgs({ args, options: optionsSchema, allowPositionals: true });
+
+        if (values.help || positionals.length === 0) {
+            console.log(`
+${colors.magenta}${colors.bold}🌀 qtex CLI${colors.reset}
+Ultra-fast LaTeX compilation powered by Tachyon-Tex
+
+${colors.bold}USAGE:${colors.reset}
+  qtex <directory> [options]
+
+${colors.bold}OPTIONS:${colors.reset}
+  -w, --watch           Watch for changes and recompile
+  -o, --output <file>   Define output filename (default: output.pdf)
+  -h, --help            Show this help message
+            `);
+            process.exit(0);
+        }
+
+        const directory = positionals[0];
+        console.log(`${colors.magenta}${colors.bold}\n🌀 qtex CLI v1.0.0 (Vanilla)${colors.reset}\n`);
+
+        if (values.watch) {
+            ui.info(`Watching for changes in: ${colors.bold}${directory}${colors.reset}`);
+            await compile(directory, values);
+
+            let isCompiling = false;
+            watch(directory, { recursive: true }, async (event, filename) => {
+                if (filename && !filename.startsWith('.') && !isCompiling) {
+                    const ext = extname(filename).toLowerCase();
+                    const outputFileName = values.output || 'output.pdf';
+
+                    // Watch for LaTeX files and images, but ignore the output PDF to avoid loops
+                    const watchExts = ['.tex', '.bib', '.sty', '.cls', '.png', '.jpg', '.jpeg', '.pdf'];
+                    const isOutputFile = basename(filename) === basename(outputFileName);
+
+                    if (watchExts.includes(ext) && !isOutputFile) {
+                        isCompiling = true;
+                        console.log(`\n${colors.blue}🔄 Change detected in ${filename}, recompiling...${colors.reset}`);
+                        await compile(directory, values);
+                        isCompiling = false;
+                    }
+                }
+            });
+        } else {
+            await compile(directory, values);
+        }
+
+    } catch (e) {
+        ui.error(e.message);
+        process.exit(1);
+    }
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "qtex",
+  "version": "1.0.0",
+  "description": "Vortex CLI: Ultra-fast cloud-based LaTeX compilation. Compile LaTeX documents in milliseconds using a high-performance Rust-powered engine without local TeX installation.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "latex",
+    "tex",
+    "compiler",
+    "tectonic",
+    "rust",
+    "cloud-latex",
+    "pdf-generator",
+    "vortex",
+    "cli",
+    "typesetting"
+  ],
+  "author": "Sergio Lázaro (srsergio)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/srsergiolazaro/qtex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/srsergiolazaro/qtex/issues"
+  },
+  "homepage": "https://github.com/srsergiolazaro/qtex#readme",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "bin": {
+    "qtex": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "directories": {
+    "example": "example"
+  }
+}

package/src/compiler.js

@@ -0,0 +1,117 @@
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { resolve, join, extname } from 'node:path';
+import { colors, ui, Spinner } from './ui.js';
+
+const API_BASE = 'https://latex.taptapp.xyz';
+
+async function getFiles(dir, baseDir = dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const res = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+                files.push(...(await getFiles(res, baseDir)));
+            }
+        } else {
+            files.push({
+                path: res,
+                relative: join(dir.replace(baseDir, ''), entry.name).replace(/^[\\\/]/, '')
+            });
+        }
+    }
+    return files;
+}
+
+export async function compile(dir, options) {
+    const outputFileName = options.output || 'output.pdf';
+    const spinner = new Spinner(`${colors.blue}Preparing compilation...`).start();
+
+    try {
+        const absoluteDir = resolve(dir);
+        const allFiles = await getFiles(absoluteDir);
+
+        const form = new FormData();
+        const validateForm = new FormData();
+        let hasLatex = false;
+
+        for (const fileObj of allFiles) {
+            const ext = extname(fileObj.path).toLowerCase();
+            const allowedExts = ['.tex', '.bib', '.sty', '.cls', '.pdf', '.png', '.jpg', '.jpeg'];
+
+            if (allowedExts.includes(ext)) {
+                const content = await readFile(fileObj.path);
+                const blob = new Blob([content]);
+                form.append('files', blob, fileObj.relative);
+
+                if (ext === '.tex') {
+                    validateForm.append('files', blob, fileObj.relative);
+                    hasLatex = true;
+                }
+            }
+        }
+
+        if (!hasLatex) {
+            spinner.fail(`${colors.yellow}No LaTeX files found in directory.`);
+            return;
+        }
+
+        // Phase 1: Validation
+        spinner.update(`${colors.cyan}Validating LaTeX...`);
+        try {
+            const validateRes = await fetch(`${API_BASE}/validate`, {
+                method: 'POST',
+                body: validateForm
+            });
+            const validation = await validateRes.json();
+
+            if (validation.valid === false) {
+                spinner.stop();
+                ui.error('Validation failed!');
+                validation.errors.forEach(err => {
+                    console.log(`  ${colors.red}• [Line ${err.line || '?'}] ${err.message}${colors.reset}`);
+                });
+                return;
+            }
+
+            if (validation.warnings?.length > 0) {
+                spinner.stop();
+                ui.warn('Validation warnings:');
+                validation.warnings.forEach(warn => console.log(`  ${colors.yellow}⚡ ${warn}${colors.reset}`));
+                spinner.start();
+            }
+        } catch (e) {
+            // Validation service unavailable, proceed anyway
+        }
+
+        // Phase 2: Compilation
+        spinner.update(`${colors.cyan}Compiling via Tachyon-Tex API...`);
+
+        const response = await fetch(`${API_BASE}/compile`, {
+            method: 'POST',
+            body: form
+        });
+
+        if (response.ok) {
+            const buffer = await response.arrayBuffer();
+            const compileTime = response.headers.get('x-compile-time-ms') || 'unknown';
+            const filesReceived = response.headers.get('x-files-received') || '0';
+
+            const outputPath = resolve(process.cwd(), outputFileName);
+            await writeFile(outputPath, Buffer.from(buffer));
+
+            spinner.succeed(`${colors.green}PDF generated in ${colors.bold}${compileTime}ms${colors.reset}`);
+            console.log(`${colors.dim}  ⚡ Files: ${filesReceived} processed${colors.reset}`);
+            console.log(`${colors.dim}  📍 Path: ${outputPath}${colors.reset}`);
+        } else {
+            const errorMsg = await response.text();
+            spinner.fail(`Compilation failed (Status ${response.status})`);
+            console.log(`\n${colors.yellow}--- Error Log ---${colors.reset}`);
+            console.log(`${colors.red}${errorMsg || 'Error details unavailable.'}${colors.reset}`);
+            console.log(`${colors.yellow}-----------------\n${colors.reset}`);
+        }
+    } catch (error) {
+        spinner.fail('An unexpected error occurred.');
+        console.error(`${colors.red}${error.message}${colors.reset}`);
+    }
+}

package/src/ui.js

@@ -0,0 +1,52 @@
+export const ESC = '\x1b[';
+export const colors = {
+    reset: `${ESC}0m`,
+    bold: `${ESC}1m`,
+    dim: `${ESC}2m`,
+    magenta: `${ESC}35m`,
+    blue: `${ESC}34m`,
+    cyan: `${ESC}36m`,
+    green: `${ESC}32m`,
+    yellow: `${ESC}33m`,
+    red: `${ESC}31m`,
+};
+
+export const ui = {
+    log: (msg) => console.log(msg),
+    error: (msg) => console.log(`${colors.red}✖ ${msg}${colors.reset}`),
+    warn: (msg) => console.log(`${colors.yellow}⚠️  ${msg}${colors.reset}`),
+    success: (msg) => console.log(`${colors.green}✔ ${msg}${colors.reset}`),
+    info: (msg) => console.log(`${colors.cyan}ℹ ${msg}${colors.reset}`),
+    clearLine: () => process.stdout.write('\r\x1b[K'),
+};
+
+export class Spinner {
+    constructor(text) {
+        this.text = text;
+        this.frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        this.index = 0;
+        this.timer = null;
+    }
+    start() {
+        this.timer = setInterval(() => {
+            process.stdout.write(`\r${colors.cyan}${this.frames[this.index]}${colors.reset} ${this.text}`);
+            this.index = (this.index + 1) % this.frames.length;
+        }, 80);
+        return this;
+    }
+    update(text) {
+        this.text = text;
+    }
+    stop(symbol = ' ', color = colors.reset) {
+        clearInterval(this.timer);
+        ui.clearLine();
+    }
+    succeed(text) {
+        this.stop();
+        console.log(`${colors.green}✔${colors.reset} ${text}`);
+    }
+    fail(text) {
+        this.stop();
+        console.log(`${colors.red}✖${colors.reset} ${text}`);
+    }
+}