commit 97f73a701f298fc724e795c3f2fc090248cb9f1b Author: Amit Dutta <mail@amit.is-a.dev> Date: Wed, 5 Aug 2026 13:11:53 +0530 v1.0.0 Diffstat:
| A | retype.yml | | | 55 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/git-mirror/build-process.md | | | 51 | +++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/git-mirror/customization.md | | | 32 | ++++++++++++++++++++++++++++++++ |
| A | src/git-mirror/deploy.md | | | 33 | +++++++++++++++++++++++++++++++++ |
| A | src/git-mirror/index.md | | | 28 | ++++++++++++++++++++++++++++ |
| A | src/githrun/cli-auth-and-tools.md | | | 46 | ++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/githrun/cli-find-download.md | | | 39 | +++++++++++++++++++++++++++++++++++++++ |
| A | src/githrun/cli-usage.md | | | 44 | ++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/githrun/configuration.md | | | 15 | +++++++++++++++ |
| A | src/githrun/index.md | | | 29 | +++++++++++++++++++++++++++++ |
| A | src/githrun/python-api.md | | | 29 | +++++++++++++++++++++++++++++ |
| A | src/githrun/vscode-extension.md | | | 45 | +++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/index.md | | | 29 | +++++++++++++++++++++++++++++ |
| A | src/mojic/algorithm.md | | | 36 | ++++++++++++++++++++++++++++++++++++ |
| A | src/mojic/index.md | | | 42 | ++++++++++++++++++++++++++++++++++++++++++ |
| A | src/mojic/installation.md | | | 34 | ++++++++++++++++++++++++++++++++++ |
| A | src/mojic/usage.md | | | 48 | ++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/osma/index.md | | | 43 | +++++++++++++++++++++++++++++++++++++++++++ |
| A | src/osma/notes.md | | | 75 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/osma/npm-api.md | | | 99 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/osma/pypi-api.md | | | 98 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/osma/quickstart.md | | | 76 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/osma/utility.md | | | 41 | +++++++++++++++++++++++++++++++++++++++++ |
| A | src/veyrix/architecture.md | | | 66 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/veyrix/faq.md | | | 22 | ++++++++++++++++++++++ |
| A | src/veyrix/index.md | | | 53 | +++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/veyrix/performance.md | | | 31 | +++++++++++++++++++++++++++++++ |
| A | src/veyrix/roadmap.md | | | 28 | ++++++++++++++++++++++++++++ |
| A | src/veyrix/security.md | | | 35 | +++++++++++++++++++++++++++++++++++ |
| A | src/veyrix/usage-guide.md | | | 41 | +++++++++++++++++++++++++++++++++++++++++ |
| A | src/veyrix/veyrix-web.md | | | 40 | ++++++++++++++++++++++++++++++++++++++++ |
| A | src/whatsapp-logger/connect-whatsapp.md | | | 17 | +++++++++++++++++ |
| A | src/whatsapp-logger/deploy-backend.md | | | 24 | ++++++++++++++++++++++++ |
| A | src/whatsapp-logger/firebase-setup.md | | | 59 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/whatsapp-logger/index.md | | | 47 | +++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/whatsapp-logger/keep-alive.md | | | 16 | ++++++++++++++++ |
| A | src/whatsapp-logger/prerequisites.md | | | 23 | +++++++++++++++++++++++ |
| A | src/whatsapp-logger/roadmap.md | | | 46 | ++++++++++++++++++++++++++++++++++++++++++++++ |
| A | src/whatsapp-logger/setup-frontend.md | | | 38 | ++++++++++++++++++++++++++++++++++++++ |
| A | src/whatsapp-logger/troubleshooting.md | | | 16 | ++++++++++++++++ |
| A | src/whatsapp-logger/usage.md | | | 16 | ++++++++++++++++ |
41 files changed, 1685 insertions(+), 0 deletions(-)
diff --git a/retype.yml b/retype.yml @@ -0,0 +1,55 @@ +input: ./src +output: docs +url: docs.amit.is-a.dev +branding: + title: Docs +links: + - text: Home + link: index.md + icon: home + - text: Website + link: https://amit.is-a.dev + icon: globe + - text: Github + link: https://github.com/notamitgamer + icon: mark-github + target: blank + - text: Sponsor + link: https://github.com/sponsors/notamitgamer + icon: heart + target: blank +edit: + repo: "https://github.com/notamitgamer/docs" + base: "/src" + branch: "main" + label: "Edit this page" +editor: + enabled: true +generator: + recase: all +markdown: + lineBreaks: soft +meta: + title: " | Docs" +search: + hotkeys: + - "/" + maxResults: 20 + minChars: 2 + mode: full + noResultsFoundMsg: "No results" + placeholder: Search +start: + open: false +snippets: + lineNumbers: + - js + - none +templating: + enabled: true + liquid: false +footer: + copyright: "© 2025-2026 amit.is-a.dev - All Rights Reserved." + links: + - text: notamitgamer/docs + link: https://github.com/notamitgamer/docs diff --git a/src/git-mirror/build-process.md b/src/git-mirror/build-process.md @@ -0,0 +1,51 @@ +--- +label: How the Build Works +icon: gear +order: 770 +--- + +# How the Build Works + +`build.sh` runs the whole pipeline, driven by GitHub Actions. Here's what it does, step by step. + +## 1. Setup & metadata + +- Detects the repo owner (`GITHUB_REPOSITORY_OWNER`, falling back to `notamitgamer` locally) +- Resolves the site's base URL from a configured Pages CNAME, or falls back to `https://<username>.github.io` +- Captures the git-mirror repo's own commit hash and build timestamp for the footer + +## 2. Copy root assets + +`style.css`, `favicon.png`, `logo.png`, and `icon.png` are copied from `assets/` into the site root (with `favicon.png` also duplicated as `favicon.ico`). + +## 3. Fetch & process each public repository + +For every public repo (minus the filtered ones): + +1. Clone it as a **bare repo** into `raw_repos/` +2. Overwrite stagit's placeholder `description` and `owner` files +3. Run `stagit` to generate the standard Log / Files / Refs / README / LICENSE pages +4. Copy `style.css`, `logo.png`, and `favicon.png` into that repo's subfolder +5. Inject an **Activity** link into stagit's nav bar on every generated page +6. Generate a custom `activity.html` page with: + - Clone URL and GitHub link + - Last commit hash + timestamp + - Approximate repo size + - A small dependency-free SVG bar graph of weekly commit activity +7. Inject a recursive, collapsible **folder tree** script into `files.html`, with hash-based URLs (`#folder=path/to/dir`) so specific folders can be linked directly and auto-expanded +8. Add a static **breadcrumb** to every individual file page under `file/`, built by walking the file's path +9. Write a `last_commit` file into the repo subfolder recording the mirror's build metadata + +## 4. Generate the central index + +`stagit-index` runs over all the bare repos to produce the root `site/index.html` landing page, listing every mirrored repository. + +## 5. Site-wide finishing touches + +- Injects a formatted build-info footer (owner, build time, git-mirror commit, stagit credit) into every generated HTML page +- Copies `CNAME` into the site output, if present +- Injects a mobile viewport meta tag into every page's `<head>` +- Generates `sitemap.xml` from every HTML file in the output +- Generates a styled `404.html` + +The final output lands in `./site`, ready to be deployed via GitHub Pages. diff --git a/src/git-mirror/customization.md b/src/git-mirror/customization.md @@ -0,0 +1,32 @@ +--- +label: Customization +order: 780 +--- + +# Customization + +## Filter repositories + +Open `build.sh` and find the `gh repo list` command. The `select` statement controls which repos are excluded — by default it skips `git-mirror`, `register`, and `osma`: + +```bash +REPOS_JSON=$(gh repo list "$USERNAME" --visibility=public --limit 100 --json name,description -q '.[] | select(.name != "git-mirror" and .name != "register" and .name != "osma")') +``` + +Edit the `select` conditions to hide forks or other specific project names. + +## Styling & assets + +Replace or edit the files inside `assets/`: + +- `style.css` +- `logo.png` +- `favicon.png` + +These get copied into the site root and into every generated repo subfolder during the build. + +## Custom domain + +If you're using a custom domain, create a file named `CNAME` in the repository root containing your domain name. The build script automatically copies it to the site output and uses it to build `sitemap.xml` URLs. + +Continue to [How the Build Works](build-process.md). diff --git a/src/git-mirror/deploy.md b/src/git-mirror/deploy.md @@ -0,0 +1,33 @@ +--- +label: Fork & Deploy +order: 790 +--- + +# How to Fork and Deploy + +Follow these steps to create and host your own version of this repository mirror. + +## 1. Fork the repository + +Click **Fork** at the top right of [github.com/notamitgamer/git-mirror](https://github.com/notamitgamer/git-mirror) to create a copy under your own GitHub account. + +## 2. Enable GitHub Actions + +GitHub automatically disables workflows in forked repositories for security reasons. + +1. Navigate to the **Actions** tab in your forked repository. +2. Click **"I understand my workflows, go ahead and enable them"**. + +## 3. Configure GitHub Pages + +1. Go to your repository **Settings**. +2. Click **Pages** in the left sidebar. +3. Under "Build and deployment", set the source to **GitHub Actions** (or the specific deployment branch, depending on how your workflow is configured to upload the `./site` directory). + +## 4. Trigger the first build + +1. Go back to the **Actions** tab. +2. Select the build/deploy workflow from the left sidebar. +3. Click **Run workflow** to fetch your repositories, generate the HTML, and deploy the site. + +Continue to [Customization](customization.md). diff --git a/src/git-mirror/index.md b/src/git-mirror/index.md @@ -0,0 +1,28 @@ +--- +label: Git Mirror +icon: repo-forked +order: 800 +--- + +# Git Mirror Site Generator + +An automated setup that generates a fast, static HTML mirror of your public GitHub repositories, using [`stagit`](https://codemadness.org/stagit.html) and GitHub Actions. + +Instead of hitting the GitHub UI, this gives you a lightweight, self-hosted browsing experience for your repos — plain HTML, no JavaScript framework, no tracking, and fast to load. + +## What it generates + +For each public repo, the build produces: + +- Standard `stagit` pages — **Log**, **Files**, **Refs**, plus **README**/**LICENSE** when present +- An added **Activity** page — clone URL, GitHub link, last commit, repo size, and a small commit-activity graph (SVG, dependency-free) +- A recursive, collapsible **folder tree** injected into `files.html` (with hash-based deep links to specific folders) +- Breadcrumb navigation on every individual file page +- A central `stagit-index` landing page listing all mirrored repos +- `sitemap.xml`, a styled `404.html`, and a build-info footer on every page (commit hash, build time, source) + +## Get started + +- [How to Fork & Deploy](deploy.md) +- [Customization](customization.md) +- [How the Build Works](build-process.md) diff --git a/src/githrun/cli-auth-and-tools.md b/src/githrun/cli-auth-and-tools.md @@ -0,0 +1,46 @@ +--- +label: CLI - Auth, Bookmarks & Tools +order: 680 +--- + +# Authentication (Private Repos & Rate Limits) + +GitHub limits unauthenticated requests to 60/hour. Logging in raises this to 5,000 and grants access to private repositories. + +```bash +githrun login ghp_YourPersonalAccessToken... +``` + +The token is stored securely in `~/.githrun/config.json`. + +# Bookmarks + +Stop copy-pasting long URLs — save them once, run them anywhere. + +```bash +# Add a bookmark +githrun bookmark add clean-db https://github.com/user/repo/blob/main/utils/cleanup.py + +# Run a bookmark +githrun run clean-db + +# List bookmarks +githrun bookmark list +``` + +# Install as a Tool + +Turn a remote Python script into a command you can run from anywhere in your terminal. + +```bash +githrun install https://github.com/user/repo/blob/main/my-tool.py --name mytool +``` + +- **Windows** — creates a `.bat` file in `~/.githrun/bin` +- **Linux/Mac** — creates an executable shim in `~/.githrun/bin` + +!!!warning +You must add `~/.githrun/bin` to your system PATH for installed tools to be runnable directly. +!!! + +Continue to [Find, Search & Download](cli-find-download.md). diff --git a/src/githrun/cli-find-download.md b/src/githrun/cli-find-download.md @@ -0,0 +1,39 @@ +--- +label: CLI - Find & Download +order: 670 +--- + +# Find & Search + +Search for files inside a remote repository without cloning it. + +```bash +# Search for files containing "config" +githrun find https://github.com/user/repo "config" +``` + +This command is interactive — you can select a result number to run it immediately. + +# Download Files & Folders + +## Download a single file + +```bash +githrun download https://github.com/user/repo/blob/main/script.py +``` + +## Download a specific folder (recursive) + +```bash +githrun download https://github.com/user/repo/tree/main/src/utils --output ./local_utils +``` + +# Show Folder Contents + +List files in a remote directory to understand the structure: + +```bash +githrun show https://github.com/user/repo/tree/main/src +``` + +Continue to [Python API](python-api.md). diff --git a/src/githrun/cli-usage.md b/src/githrun/cli-usage.md @@ -0,0 +1,44 @@ +--- +label: CLI - Install & Run +order: 690 +--- + +# Installation + +```bash +pip install githrun +``` + +# Run Remote Code + +Execute a script directly from a URL. + +## Basic execution + +```bash +githrun run https://github.com/user/repo/blob/main/script.py +``` + +## Run gists + +```bash +githrun run https://gist.github.com/user/1234567890abcdef +``` + +## Auto-install dependencies + +If a remote script needs packages you don't have (e.g. pandas, requests), run it in an isolated environment: + +```bash +githrun run https://github.com/user/repo/blob/main/data.py --auto-install +``` + +## Inspect before running + +View the source with syntax highlighting before executing it — a safety check: + +```bash +githrun run https://github.com/user/repo/blob/main/script.py --inspect +``` + +Continue to [Auth, Bookmarks & Tool Install](cli-auth-and-tools.md). diff --git a/src/githrun/configuration.md b/src/githrun/configuration.md @@ -0,0 +1,15 @@ +--- +label: Configuration +icon: gear +order: 640 +--- + +# Configuration + +Githrun stores configuration and cache files in your home directory: + +| Path | Purpose | +|---|---| +| `~/.githrun/config.json` | Tokens, bookmarks | +| `~/.githrun/cache/` | Cached API responses | +| `~/.githrun/bin/` | Installed tools | diff --git a/src/githrun/index.md b/src/githrun/index.md @@ -0,0 +1,29 @@ +--- +label: Githrun +icon: terminal +order: 700 +--- + +# Githrun + +Githrun is a command-line tool and VS Code extension that lets you execute, explore, and install Python scripts directly from GitHub and Gists — handling dependencies, private repositories, and local tool installation along the way. + +## Features + +- **Remote execution** — run scripts from GitHub or Gist URLs instantly +- **Auto-dependency management** — creates temporary virtual environments and installs missing packages with `--auto-install` +- **Private repo access** — authenticate with GitHub tokens for private code and higher API rate limits +- **Bookmarks** — save long URLs as short aliases (`githrun run clean-db`) +- **Tool installation** — install remote scripts as permanent local CLI commands +- **Recursive downloads** — download entire folders or sub-directories from a repo +- **Interactive search** — search files in a repo and run results immediately +- **Smart caching** — caches API responses to speed up repeated searches and reduce API usage + +## Get started + +- [CLI: Installation & Running Scripts](cli-usage.md) +- [CLI: Auth, Bookmarks & Tool Install](cli-auth-and-tools.md) +- [CLI: Find, Search & Download](cli-find-download.md) +- [Python API](python-api.md) +- [VS Code Extension](vscode-extension.md) +- [Configuration](configuration.md) diff --git a/src/githrun/python-api.md b/src/githrun/python-api.md @@ -0,0 +1,29 @@ +--- +label: Python API +icon: code +order: 660 +--- + +# Python API Usage + +Githrun can be used inside your own Python scripts. + +```python +import githrun + +# 1. Search a repository +results = githrun.search_repository("https://github.com/user/repo", "test") +for item in results: + print(item['path'], item['raw_url']) + +# 2. Download a file +githrun.download_file("https://github.com/user/repo/blob/main/script.py", output_path="script.py") + +# 3. Download a full folder +githrun.download_folder("https://github.com/user/repo/tree/main/src") + +# 4. Execute code programmatically +exit_code = githrun.execute_remote_code("https://github.com/user/repo/blob/main/script.py", args=["--verbose"]) +``` + +Continue to [VS Code Extension](vscode-extension.md). diff --git a/src/githrun/vscode-extension.md b/src/githrun/vscode-extension.md @@ -0,0 +1,45 @@ +--- +label: VS Code Extension +icon: file-code +order: 650 +--- + +# VS Code Extension + +## Installation & setup + +### 1. Install the extension + +- **Marketplace** — search for "Githrun" in the VS Code Extensions view and click Install +- **Manual** — if installing from a VSIX file, go to Extensions → **...** → Install from VSIX + +### 2. Install the core CLI (required) + +The extension acts as a bridge to the Githrun CLI — you must have it installed on your system: + +```bash +pip install githrun +``` + +## Extension features & usage + +### CodeLens integration + +The extension automatically scans Markdown, Python, and Text files for GitHub or Gist URLs. Look for the "Run with Githrun" link appearing above any detected URL — click it to open a terminal and run the script immediately. + +### Context menu + +Highlight any GitHub URL in your editor, right-click the selection, and choose **Githrun: Run Selected Text**. + +### Command palette + +Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac), type `Githrun: Run from URL...`, and paste your target link. + +## Extension settings + +The extension tries to auto-detect your Githrun installation: + +1. First checks for `githrun` in your global PATH +2. If not found, falls back to `python -m githrun` (or `python3` on Mac/Linux) + +Continue to [Configuration](configuration.md). diff --git a/src/index.md b/src/index.md @@ -0,0 +1,29 @@ +--- +label: Home +icon: home +order: 1000 +--- + +# Amit's Docs + +Centralized documentation for Amit's projects — pick one below to get started. + +### Projects + +#### [WhatsApp Logger (Self-Hosted)](/whatsapp-logger/) +Privacy-focused, self-hosted WhatsApp archiving tool. Captures messages — including deleted ones — via a linked device connection and stores them in your own Firebase database. + +#### [Git Mirror Site Generator](/git-mirror/) +Automated setup that generates a fast, static HTML mirror of your public GitHub repositories using `stagit` and GitHub Actions. + +#### [Mojic](/mojic/) +CLI tool that obfuscates C source code into a randomized, password-seeded stream of emojis, using an AES-256-CTR PRNG and HMAC-sealed integrity checks. *(Discontinued — install from source.)* + +#### [Githrun](/githrun/) +CLI tool and VS Code extension for executing, exploring, and installing Python scripts directly from GitHub and Gists, with dependency handling and private repo support. + +#### [Veyrix IDE](/veyrix/) +Offline-first, privacy-focused PWA code editor that runs entirely in the browser, with local IndexedDB storage, snapshot version history, and dual sharing mechanics. + +#### [OSMA (Open Source Module Archive)](/osma/) +Lightning-fast, static search archive for querying NPM and PyPI packages, bypassing live registry bottlenecks with frozen snapshots and a FastAPI + SQLite backend. diff --git a/src/mojic/algorithm.md b/src/mojic/algorithm.md @@ -0,0 +1,36 @@ +--- +label: How It Works +icon: beaker +order: 720 +--- + +# Under the Hood: Operation Ironclad + +Mojic v2.1.0 implements a custom crypto-system dubbed "Operation Ironclad." + +## 1. Derivation phase + +- **Input:** user password + 32-byte random salt +- **KDF:** `Scrypt` (N=16384, r=8, p=1) +- **Output:** 80 bytes — 32 bytes AES key, 16 bytes AES IV, 32 bytes HMAC auth key + +## 2. The Emoji Universe + +The engine generates a universe of roughly 1,100 valid unicode characters (emoticons, transport, symbols), then **shuffles** it using the AES-256-CTR CSPRNG initialized with the derived key. + +## 3. Polymorphic encryption + +- **C keywords:** the engine detects C keywords (e.g. `while`) and assigns each one a "base emoji" from the shuffled universe. +- **The twist:** it doesn't just print the base emoji — it calculates a random offset using the PRNG to pick a *different* emoji that still maps back to the keyword. That means `int` might render as 🚀 on line 1 and 🌮 on line 5, making frequency analysis useless. + +## 4. XOR whitening + +Before encoding non-keyword data (variable names, strings, whitespace), the engine generates a random mask from the AES stream and XORs the raw data with it. This turns repetitive patterns — like indentation or common variable names — into white noise before they're converted to emojis. + +## 5. Base-1024 encoding + +The whitened data is buffered into 5-byte chunks, treated as a single large integer, and converted into 4 base-1024 digits, each mapped to an emoji. + +## 6. The header + +The salt and a 4-byte auth check are written to the file header using the Moon/Clock alphabet (`🌑🌒🌓🌔...`). This lets Mojic report "Incorrect Password" instantly, rather than churning out garbage data first. diff --git a/src/mojic/index.md b/src/mojic/index.md @@ -0,0 +1,42 @@ +--- +label: Mojic +icon: lock +order: 750 +--- + +# Mojic + +**Operation Ironclad: obfuscate C source code into a randomized, password-seeded stream of emojis.** + +Mojic (Magic + Emoji + Logic) is a CLI tool that transforms readable C code into an unrecognizable, chaotic stream of emojis. Unlike a simple substitution cipher, Mojic uses your password to seed a cryptographically strong PRNG, creating a unique "Emoji Universe" and rolling cipher for every session. + +!!!danger Project discontinued (v2.1.5) +Mojic is discontinued. v2.1.5 is the final patch to the GitHub repository. + +The maintainer lost access to the npm account (forgotten password, and the recovery passcode file was lost during a Linux migration), so `npm install mojic` currently fails with a 404 — the published `@notamitgamer/mojic` dependency can no longer be patched. + +**To keep using it, install from source instead:** +```bash +git clone https://github.com/notamitgamer/mojic.git +cd mojic +npm install +npm link +``` +This makes the `mojic` command available globally, same as an npm install would. +!!! + +## Key features + +- **AES-256-CTR PRNG** — a cryptographically secure PRNG (seeded via Scrypt) drives shuffling and polymorphism +- **Polymorphic keywords** — common C keywords (`int`, `void`, `return`) map to emojis that change every time they appear, based on PRNG state — frequency analysis doesn't work +- **XOR whitening** — raw data (whitespace, variable names) is XORed with the AES keystream before encoding, so repeating patterns like 4-space indentation never produce the same emoji sequence twice +- **Base-1024 compression** — non-keyword code is compressed with a custom scheme (5 bytes → 4 emojis) to keep file size manageable +- **Integrity sealed** — every file ends with an HMAC-SHA256 signature; tampering triggers an immediate `FILE_TAMPERED` error +- **Moon Header Protocol** — metadata (salt + auth check) is encoded with a Moon/Clock phase alphabet (`🌑🌒🕐`), so an incorrect password is detected instantly, before decryption even starts +- **Stream architecture** — built on Node.js `Transform` streams for large files with minimal memory footprint + +## Get started + +- [Installation](installation.md) +- [CLI Usage](usage.md) +- [How It Works (Operation Ironclad)](algorithm.md) diff --git a/src/mojic/installation.md b/src/mojic/installation.md @@ -0,0 +1,34 @@ +--- +label: Installation +order: 740 +--- + +# Installation + +!!!warning npm install is currently broken +The published npm package is discontinued and `npm install -g mojic` will fail with a 404. Use the "from source" method below. +!!! + +## From source (recommended, currently required) + +```bash +# Clone and navigate to the directory +git clone https://github.com/notamitgamer/mojic.git +cd mojic + +# Install dependencies and link it globally to use the 'mojic' command +npm install +npm link +``` + +## Via npm (currently broken) + +```bash +npm install -g mojic +``` + +Or without installing: + +```bash +npx mojic encode main.c +``` diff --git a/src/mojic/usage.md b/src/mojic/usage.md @@ -0,0 +1,48 @@ +--- +label: CLI Usage +order: 730 +--- + +# CLI Usage + +## 1. Encrypting code (`encode`) + +Transforms a `.c` file into a `.mojic` file. You'll be prompted to create a password — it's required to decrypt. + +```bash +# Encrypt a single file +mojic encode main.c + +# Encrypt an entire directory recursively +mojic encode ./src -r + +# Flatten/minify code structure before encryption (removes newlines/indentation) +mojic encode main.c --flat +``` + +## 2. Decrypting code (`decode`) + +Restores the original C code from a `.mojic` file. + +```bash +# Decrypt a single file +mojic decode main.mojic + +# Decrypt an entire directory recursively +mojic decode ./src -r +``` + +## 3. Security & rotation tools (`srt`) + +Manage encrypted files without ever revealing their plaintext contents. + +```bash +# Rotate password: changes the password of an encrypted file +mojic srt --pass secret.mojic + +# Re-encrypt: re-shuffles the entropy (new salt) with the SAME password +# useful to change the visual emoji pattern without changing the password +mojic srt --re secret.mojic +``` + +Continue to [How It Works](algorithm.md). diff --git a/src/osma/index.md b/src/osma/index.md @@ -0,0 +1,43 @@ +--- +label: OSMA +icon: package +order: 550 +--- + +# OSMA (Open Source Module Archive) + +**Registry lookups, without the wait.** OSMA is a lightning-fast, static search archive for querying open-source packages across NPM and PyPI, bypassing live registry bottlenecks. + +## Why it exists + +Looking up package details on the official registries usually means dealing with: + +1. **Fastly security checks** — CAPTCHAs or verification screens just to view a text page +2. **The multi-click tax** — clicking through 2-3 pages just to find a version tag or repo link + +**The fix:** complete static snapshots of both registries were taken — **NPM at 2026-04-29 09:42 IST**, **PyPI at 2026-04-29 08:45 IST** — and indexed into a custom backend. This lets you instantly search and verify packages without ever hitting a live registry rate limit. Clicking a package in the UI still fetches its extended live details securely via a side-panel. + +## Live explorers & docs + +- **Home:** [data.amit.is-a.dev](https://data.amit.is-a.dev) +- **NPM Explorer:** [data.amit.is-a.dev/npm](https://data.amit.is-a.dev/npm) +- **PyPI Explorer:** [data.amit.is-a.dev/pypi](https://data.amit.is-a.dev/pypi) +- **API Docs (live):** [data.amit.is-a.dev/docs](https://data.amit.is-a.dev/docs) + +## How the backend works + +The backend runs on **FastAPI**, serving static `.csv` snapshots pulled securely from HuggingFace datasets. + +- **SQLite indexing** — on first boot, the server downloads the multi-gigabyte dataset and builds an optimized, indexed SQLite database (WAL mode) +- **Speed** — because the dataset is localized, `/search` and `/browse` respond in milliseconds +- **Rate limiting** — strict limits (10 requests/minute, 100/hour) protect the free-tier infrastructure, enforced via `slowapi`; developers can request an `X-Bypass-Token` via a GitHub issue +- **Ranking logic** — search results are ranked `0` exact match → `1` starts with query → `2` contains query +- **Limitation** — as a frozen archive, packages published or deleted after April 2026 aren't indexed + +## Get started + +- [Quick Start](quickstart.md) +- [NPM API Reference](npm-api.md) +- [PyPI API Reference](pypi-api.md) +- [Utility Endpoints](utility.md) +- [Notes, Limits & FAQ](notes.md) diff --git a/src/osma/notes.md b/src/osma/notes.md @@ -0,0 +1,75 @@ +--- +label: Notes & FAQ +icon: question +order: 500 +--- + +# Notes & Reference + +## Limits & notes + +**Rate limits** — APIs are strictly rate-limited to 10 requests/minute and 100 requests/hour per IP to protect the free-tier infrastructure. Send the `X-Bypass-Token` header to override this. + +**Data freshness** — both datasets are snapshots. NPM was frozen `2026-04-29 09:42 IST`, PyPI `2026-04-29 08:45 IST`. Packages published after these dates aren't indexed. + +**CORS** — both APIs have `Access-Control-Allow-Origin: *`, so you can call them directly from any browser-based frontend with no proxy needed. + +**Cold starts** — on first boot after a deployment, each server downloads its dataset and builds a SQLite index (~1 min). `/health` returns `503` during this window. UptimeRobot prevents this in normal operation. + +## Response schema + +`results` arrays from `/browse` or `/search` contain objects with: + +| Field | Type | Description | +|---|---|---| +| `no` | integer | Stable, sequential ID/rank of the package within the snapshot database | +| `name` | string | The exact, registered name of the package | +| `version` | string | Version string available at the time the snapshot was taken | +| `url` | string | Absolute link to the package on the official registry website | +| `rank` | integer | *(`/search` only)* Match quality: `0` exact, `1` starts-with, `2` contains | + +## Common errors + +**`404` Not Found** — the API URL path is incorrect or misspelled (e.g. `/searc` instead of `/search`). + +**`422` Unprocessable Entity** — `/search` was called without the required `q` parameter, or the query was under 2 characters. + +**`429` Too Many Requests** — you exceeded the 10/min or 100/hour rate limit. The response includes a `Retry-After` header. + +**`503` Service Unavailable** — the server was asleep (cold start) and is downloading the dataset / building its SQLite index. Normal on free-tier hosting; usually resolves within a minute. + +!!!warning Still having trouble? +If you're seeing continuous `500` errors or found a bug, [open an issue on GitHub](https://github.com/notamitgamer/osma/issues) or email [mail@amit.is-a.dev](mailto:mail@amit.is-a.dev). +!!! + +## FAQ + +**What exactly is OSMA?** +A heavily optimized, static API serving historical snapshots of the NPM and PyPI registries — search packages and view base version data instantly without live registry rate limits or CAPTCHAs. + +**Why can't I find a recently published package?** +The datasets are frozen snapshots from April 29, 2026. Anything published, renamed, or deleted after that date won't appear. + +**Is there rate limiting?** +Yes — 10 requests/minute and 100/hour per IP via SlowAPI. Open a GitHub issue to request an `X-Bypass-Token` if you need it disabled. + +**Do I need an API key?** +No — the APIs are fully open and require no authentication for standard usage within the rate limits. + +**Can I use this in a frontend app directly?** +Yes — both APIs have open CORS (`Access-Control-Allow-Origin: *`), so browser apps can fetch directly with no proxy. + +**What does the `rank` field mean?** +`0` = exact match, `1` = starts with the query, `2` = contains the query somewhere in the name. + +**Why does `/health` sometimes return 503?** +The server went to sleep from inactivity. On waking (a "cold start") it needs 1–2 minutes to download the CSV snapshot and rebuild its index — it returns `503` while loading. + +**How many packages are indexed?** +Roughly 3.88 million NPM packages and 793,000 PyPI packages as of the current snapshots. Check `/stats` for exact live numbers. + +**Are other registries (RubyGems, Cargo) planned?** +The current focus is strictly NPM and PyPI; other ecosystems may be considered with enough demand. + +**How do I report a bug or vulnerability?** +General bugs/UI issues → [open a GitHub issue](https://github.com/notamitgamer/osma/issues). Security vulnerabilities → email [mail@amit.is-a.dev](mailto:mail@amit.is-a.dev) directly instead of filing a public issue. diff --git a/src/osma/npm-api.md b/src/osma/npm-api.md @@ -0,0 +1,99 @@ +--- +label: NPM API +icon: package-dependencies +order: 530 +--- + +# NPM API + +**Base URL:** `https://notamitgamer-osma-npm-api.hf.space` + +## GET /ping + +Uptime check — always returns 200. Lightweight endpoint for UptimeRobot or health monitors; doesn't query the database. + +```bash +curl https://notamitgamer-osma-npm-api.hf.space/ping +``` + +```json +{ "ping": "pong" } +``` + +## GET /health + +Server status + total package count. Returns `200` with the package count once the database is ready; returns `503` if it's still initializing after a cold start. + +```bash +curl https://notamitgamer-osma-npm-api.hf.space/health +``` + +```json +{ + "status": "ok", + "total_packages": 3881465 +} +``` + +## GET /stats + +Dataset metadata and package count, intended for dashboard stats bars. + +```bash +curl https://notamitgamer-osma-npm-api.hf.space/stats +``` + +```json +{ + "total_npm_packages": 3881465, + "source": "npmjs.com", + "note": "Snapshot dataset — updated periodically." +} +``` + +## GET /browse + +Paginated package list, ordered by `package_no`. + +| Parameter | Type | Default | Max | Required | Description | +|---|---|---|---|---|---| +| `page` | integer | 1 | — | optional | Page number, 1-indexed | +| `limit` | integer | 200 | 500 | optional | Rows per page | + +```bash +curl "https://notamitgamer-osma-npm-api.hf.space/browse?page=1&limit=5" +``` + +```json +{ + "page": 1, + "limit": 5, + "results": [ + { "no": 1, "name": "--123hoodmane-pyodide", "version": "latest", "url": "https://www.npmjs.com/package/..." } + ] +} +``` + +## GET /search + +Ranked search across all packages. Results are ranked by match quality — exact match (`0`) first, starts-with (`1`) second, contains (`2`) last — then sorted alphabetically within each rank. + +| Parameter | Type | Default | Max | Required | Description | +|---|---|---|---|---|---| +| `q` | string | — | 100 chars | required | Search query, min 2 characters | +| `limit` | integer | 250 | 500 | optional | Max results to return | + +```bash +curl "https://notamitgamer-osma-npm-api.hf.space/search?q=react&limit=5" +``` + +```json +{ + "query": "react", + "count": 250, + "results": [ + { "no": 42, "name": "react", "version": "18.3.1", "url": "...", "rank": 0 }, + { "no": 88, "name": "react-dom", "version": "18.3.1", "url": "...", "rank": 1 } + ] +} +``` diff --git a/src/osma/pypi-api.md b/src/osma/pypi-api.md @@ -0,0 +1,98 @@ +--- +label: PyPI API +icon: package-dependents +order: 520 +--- + +# PyPI API + +**Base URL:** `https://notamitgamer-osma-pypi-api.hf.space` + +## GET /ping + +Uptime check — always returns 200. Lightweight endpoint for UptimeRobot or health monitors; doesn't query the database. + +```bash +curl https://notamitgamer-osma-pypi-api.hf.space/ping +``` + +```json +{ "ping": "pong" } +``` + +## GET /health + +Server status + total package count. Returns `200` when the database is ready; returns `503` during cold-start initialization. + +```bash +curl https://notamitgamer-osma-pypi-api.hf.space/health +``` + +```json +{ + "status": "ok", + "total_packages": 780432 +} +``` + +## GET /stats + +Total package count and dataset source metadata. + +```bash +curl https://notamitgamer-osma-pypi-api.hf.space/stats +``` + +```json +{ + "total_pypi_packages": 780432, + "source": "pypi.org", + "note": "Snapshot dataset — updated periodically." +} +``` + +## GET /browse + +Paginated package list, ordered by `package_no`. + +| Parameter | Type | Default | Max | Required | Description | +|---|---|---|---|---|---| +| `page` | integer | 1 | — | optional | Page number, 1-indexed | +| `limit` | integer | 200 | 500 | optional | Rows per page | + +```bash +curl "https://notamitgamer-osma-pypi-api.hf.space/browse?page=1&limit=5" +``` + +```json +{ + "page": 1, + "limit": 5, + "results": [ + { "no": 1, "name": "0", "version": "0.1.0", "url": "https://pypi.org/project/0/" } + ] +} +``` + +## GET /search + +Ranked search across all packages. `0` = exact match, `1` = starts-with, `2` = contains. + +| Parameter | Type | Default | Max | Required | Description | +|---|---|---|---|---|---| +| `q` | string | — | 100 chars | required | Search query, min 2 characters | +| `limit` | integer | 250 | 500 | optional | Max results to return | + +```bash +curl "https://notamitgamer-osma-pypi-api.hf.space/search?q=requests&limit=5" +``` + +```json +{ + "query": "requests", + "count": 87, + "results": [ + { "no": 512, "name": "requests", "version": "2.31.0", "url": "...", "rank": 0 } + ] +} +``` diff --git a/src/osma/quickstart.md b/src/osma/quickstart.md @@ -0,0 +1,76 @@ +--- +label: Quick Start +order: 540 +--- + +# Quick Start + +OSMA has fully open CORS and requires no authentication keys, so you can start fetching package data immediately — from a backend script, a CLI tool, or directly inside a browser application. + +## JavaScript (browser & Node.js) + +CORS is fully open (`Access-Control-Allow-Origin: *`), so you can use the native `fetch` API directly. This example queries the NPM snapshot for `react`: + +```javascript +async function getPackageVersion(query) { + const url = `https://notamitgamer-osma-npm-api.hf.space/search?q=${encodeURIComponent(query)}&limit=1`; + + try { + const response = await fetch(url); + if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`); + + const data = await response.json(); + if (data.results && data.results.length > 0) { + const pkg = data.results[0]; + console.log(`${pkg.name} | Version: ${pkg.version} | Rank: ${pkg.rank}`); + console.log(`Registry Link: ${pkg.url}`); + } else { + console.log("Package not found in the April 2026 snapshot."); + } + } catch (error) { + console.error("Failed to fetch OSMA data:", error); + } +} + +getPackageVersion("react"); +``` + +## Python + +For Python apps, tools, or data analysis scripts, `requests` makes querying the PyPI snapshot simple: + +```python +import requests + +def get_package_version(query): + url = f"https://notamitgamer-osma-pypi-api.hf.space/search?q={query}&limit=1" + try: + response = requests.get(url) + response.raise_for_status() + data = response.json() + + if data.get("results"): + pkg = data["results"][0] + print(f"{pkg['name']} | Version: {pkg['version']} | Rank: {pkg['rank']}") + print(f"Registry Link: {pkg['url']}") + else: + print("Package not found in the April 2026 snapshot.") + + except requests.exceptions.RequestException as e: + print(f"Failed to fetch OSMA data: {e}") + +if __name__ == "__main__": + get_package_version("requests") +``` + +## Command line (cURL) + +Fastest way to test an endpoint from your terminal: + +```bash +curl -s "https://notamitgamer-osma-npm-api.hf.space/search?q=express&limit=3" | jq +``` + +!!!info Rate limits apply +These endpoints are subject to the standard free-tier rate limits (10 requests/minute, 100/hour). If you're writing a script that loops through hundreds of packages, you'll need an `X-Bypass-Token` — see [Utility Endpoints](utility.md). +!!! diff --git a/src/osma/utility.md b/src/osma/utility.md @@ -0,0 +1,41 @@ +--- +label: Utility Endpoints +icon: tools +order: 510 +--- + +# Utility Endpoints + +These endpoints are available on both the NPM and PyPI APIs. Examples below use the NPM base URL. + +## GET /debug-ip + +Returns the IP address the API proxy recorded for your request, along with parsed headers — useful for troubleshooting rate-limit blocks across networks. + +```bash +curl https://notamitgamer-osma-npm-api.hf.space/debug-ip +``` + +## GET /get-bypass + +Issues a cryptographically signed token that lets you skip all rate limits for 1 hour. Requires the correct `secret` parameter. Include the returned token on subsequent requests as the `X-Bypass-Token` header. + +| Parameter | Type | Required | Description | +|---|---|---|---| +| `secret` | string | required | The developer bypass secret | + +```bash +curl "https://notamitgamer-osma-npm-api.hf.space/get-bypass?secret=YOUR_SECRET_HERE" +``` + +```json +{ + "bypass_token": "1714420000:a1b2c3d4...", + "valid_for_seconds": 3600, + "usage": "Send as header: X-Bypass-Token: <token>" +} +``` + +## GET /rebuild + +Forces the server to re-download the latest CSV dataset from HuggingFace and rebuild the SQLite database in the background. Requires the `secret` parameter. Responds with `503` while rebuilding. diff --git a/src/veyrix/architecture.md b/src/veyrix/architecture.md @@ -0,0 +1,66 @@ +--- +label: Architecture & State +icon: cpu +order: 580 +--- + +# Architecture & State Management + +## Visual system design + +Data flows through three strictly isolated layers: + +- **Presentation layer** — Ace Editor & vanilla DOM UI, reading via `state.editor.getValue()` +- **Local persistence** — IndexedDB (`VeyrixFS`), written via `DB.save(state.files)` +- **Cloud share (lazy)** — Firebase Firestore, written via `addDoc(shared_snippets)` — only touched when the user explicitly shares to the cloud + +## State management pattern + +To maintain extreme performance on low-end mobile devices, Veyrix eschews frameworks like React or Vue. Instead it relies on a mutable, global singleton `state` object. UI updates happen through explicit imperative functions triggered by state mutations, avoiding full tree diffing. + +```javascript +// Global State Singleton +const state = { + files: [], // Array of File objects + activeFileId: null, // ID of currently rendered file + editor: null, // Ace Editor instance reference + db: null, // IndexedDB connection instance + renameTargetId: null // Transient state for UI modals +}; +``` + +**Architectural decision record (ADR):** the Ace Editor manages its own complex internal state (cursors, selections, undo stacks). Wrapping it in a reactive framework often causes race conditions during rapid typing. By keeping the source of truth in `state.editor` and extracting `value` asynchronously via debounced events, Veyrix achieves sub-16ms frame times. + +## Local storage model (IndexedDB) + +Persistence is managed entirely via the browser's native IndexedDB API through a Promisified wrapper. The database is named `VeyrixFS` (Version 1). + +### Schema: `files` ObjectStore + +KeyPath: `id` + +```typescript +// TypeScript representation of the IndexedDB record +interface VeyrixFile { + id: string; // e.g., "f_a1b2c3d4e_1679000000" + name: string; // Base filename (e.g., "app") + ext: string; // Extension (e.g., "js", "html") + content: string; // Raw string payload of the editor + unsaved: boolean; // Tracks dirty state for the UI + lastModified: number; // Epoch timestamp + snapshotCounter?: number; + snapshots?: Snapshot[]; // Array (max length: 5, FIFO eviction) +} +``` + +## Cloud & synchronization strategy + +Veyrix uses a zero-cost initial load strategy: Firebase SDKs (App, Auth, Firestore) are **not** bundled or loaded on startup. They're dynamically imported via ES Modules only when a user initiates a "Cloud Share." + +### 1. Fast local share (LZ-String) + +Compresses the payload with `LZString.compressToEncodedURIComponent`, yielding a base64-like URI-safe string appended directly to the URL. Entirely offline, entirely client-side. + +### 2. Cloud share (Firestore) + +Authenticates using `signInAnonymously()`, pushes the payload to the `shared_snippets` root collection, and returns a lightweight document ID reference in the URL. diff --git a/src/veyrix/faq.md b/src/veyrix/faq.md @@ -0,0 +1,22 @@ +--- +label: FAQ +icon: question +order: 530 +--- + +# Frequently Asked Questions + +**Where are my files stored?** +All files are stored locally on your device inside your browser's secure IndexedDB. They're never uploaded to any server automatically — you maintain full ownership and privacy of your code. Only cloud share sends files to a server. + +**Do I need an internet connection to use Veyrix?** +No. Once loaded in your browser for the first time, its Service Worker caches the application, so you can use the IDE entirely offline. An internet connection is only needed for "Cloud Share." + +**Can I recover a deleted file?** +No. Deleting a file from the sidebar removes it permanently from local IndexedDB, along with all associated snapshots. Use the Download feature to keep manual backups of important code. + +**What languages does Veyrix support?** +Syntax highlighting for 50+ languages via Ace Editor. Common formats — HTML, CSS, JavaScript, TypeScript, Python, Markdown, JSON, YAML, XML — are auto-detected from the file extension. + +**Can I install Veyrix as an app?** +Yes — it's a Progressive Web App. Tap the menu button, then "Install Web App." It runs fullscreen without browser toolbars. diff --git a/src/veyrix/index.md b/src/veyrix/index.md @@ -0,0 +1,53 @@ +--- +label: Veyrix IDE +icon: browser +order: 600 +--- + +# Veyrix IDE + +_v1.1.0 — Stable_ + +Veyrix is a lightweight, offline-first Progressive Web App (PWA) that turns your browser into a highly responsive code editor. It's designed to run smoothly in strict or restricted browser environments, keeping all processing and storage entirely client-side with no backend server. + +## Why use it + +- **Absolute privacy** — your files never leave your device; everything is saved in the browser's local IndexedDB unless you explicitly use cloud share +- **Blazing fast** — bypasses heavy virtual DOMs in favor of a vanilla JavaScript architecture, so it runs smoothly on low-end devices +- **True offline mode** — install as a PWA and write code anywhere, no internet connection required +- **Built-in time machine** — save snapshots of your files to instantly roll back to previous versions, no Git setup needed + +## Core technology stack + +| Component | Version | Role | +|---|---|---| +| Ace Editor | v1.32.6 | Core text engine | +| IndexedDB | — | Local persistence layer | +| LZ-String | v1.5.0 | URL compression (local share) | +| Firebase | v11.6.1 | Cloud share (loaded on demand only) | + +Veyrix bypasses Virtual DOM overhead entirely — it uses a vanilla JS monolithic state architecture paired directly with the Ace Editor engine, rather than a framework like React or Vue. + +## Getting started + +Visit the live site to start using Veyrix IDE immediately — no installation required. To install as a PWA, tap the menu button and select **Install Web App**; it then runs fullscreen without browser toolbars. + +## Explore the docs + +- [Usage Guide](usage-guide.md) — files, editing, snapshots, sharing +- [Architecture & State Management](architecture.md) — state singleton, IndexedDB schema, cloud sync strategy +- [Security & Threat Model](security.md) — zero-knowledge password hashing, what's and isn't protected +- [Veyrix Web (Multi-File IDE)](veyrix-web.md) — the separate multi-file environment, live preview engine, ZIP export +- [Performance & Error Handling](performance.md) — benchmarks vs. VS Code Web / CodeSandbox, failure modes +- [Limitations & Roadmap](roadmap.md) +- [FAQ](faq.md) + +## Support & contact + +- General inquiries: mail@amit.is-a.dev +- Important matters: amitdutta4255@gmail.com +- Developer portfolio: [amit.is-a.dev](https://amit.is-a.dev) + +## Legal disclaimer & licensing + +Veyrix IDE and its documentation are provided "as is" under the **Apache License 2.0**, without warranty of any kind, express or implied. The creator reserves the right to modify or permanently discontinue the project at any time without prior notice, is not responsible for data loss, service interruptions, or damages arising from use of the software, and places sole responsibility for local data management on the user. diff --git a/src/veyrix/performance.md b/src/veyrix/performance.md @@ -0,0 +1,31 @@ +--- +label: Performance & Errors +icon: zap +order: 550 +--- + +# Performance & Benchmarks + +By stripping away Webpack overhead, Virtual DOM reconciliation, and heavy language servers, Veyrix operates on a fraction of the hardware requirements of modern cloud IDEs. + +| Environment | Base RAM (idle) | Editor engine | Time to interactive | +|---|---|---|---| +| Veyrix IDE | ~30MB – 42MB | Ace Editor (vanilla) | < 0.5 seconds | +| VS Code Web | ~350MB+ | Monaco + Web Workers | 2.5 – 4 seconds | +| CodeSandbox | ~500MB+ | Monaco + Container VM | 4 – 8 seconds | + +## Why it's better for mobile / low-end devices + +- **Debounced I/O** — IndexedDB writes are debounced by 500ms, ensuring zero main-thread blockage during rapid typing +- **No Monaco overhead** — Monaco is powerful but struggles on low-end Androids due to heavy worker threading; Ace Editor is substantially lighter +- **Visual viewport anchoring** — PWA implementations often suffer layout thrashing when the soft keyboard appears; Veyrix anchors directly to the `window.visualViewport` API, freezing the reflow + +# Error Handling Behavior + +## "Incognito" / Private Mode restraints + +Safari and Firefox frequently restrict or completely block IndexedDB access in Private Browsing. If `DB.init()` fails, Veyrix degrades gracefully to an in-memory volatile state. A UI toast warns the user that files will be lost when the tab closes, prompting manual downloads. + +## DOMException: QuotaExceededError + +Triggered when the device runs out of disk space, or the browser's origin quota is exceeded. Veyrix catches this in the `DB.save()` promise rejection, halting autosave and notifying the user to clear space or delete older snapshots. diff --git a/src/veyrix/roadmap.md b/src/veyrix/roadmap.md @@ -0,0 +1,28 @@ +--- +label: Limitations & Roadmap +icon: milestone +order: 540 +--- + +# Current Limitations + +- **Flat file system** — the main IDE has no directory/subfolder support; flat array mapping only (Veyrix Web solves this separately with a true VFS) +- **Snapshot limit** — hardcoded FIFO limit of 5 snapshots per file, to prevent storage quota bloat +- **No language servers** — relies entirely on basic Ace autocompletion arrays; no deep IntelliSense (LSP) +- **Single view** — split-pane or multi-tab rendering isn't yet supported in the main IDE's DOM structure + +# Development Roadmap + +## Core IDE + +**v1.1.0** — Removed the Ace.js worker to reduce RAM usage. + +**v1.0.9** — Re-engineered the file sharing logic to use `application/octet-stream` and URI-context anchoring, bypassing strict Desktop OS security blocks that previously triggered "Permission Denied" errors. + +**v1.0.8** — Updated version history logic to trigger a confirmation modal before restoration, preventing accidental data loss and ensuring a clean editor state after recovery. + +## Web IDE + +**v1.0.2** — Implemented a draggable split-pane interface (Dynamic Viewport Resizer), letting users manually adjust preview width to simulate and test designs across device breakpoints. + +**v1.0.1** — Introduced nested folder mapping, batch file uploads, and a persistence-linked tab system for navigating complex project structures (Advanced File System & Workspace). diff --git a/src/veyrix/security.md b/src/veyrix/security.md @@ -0,0 +1,35 @@ +--- +label: Security & Threat Model +icon: shield +order: 570 +--- + +# Cryptography & Security Model + +## Zero-knowledge cloud password protection + +When a user applies a password to a Cloud Share snippet, the plaintext password is **never** transmitted to Firebase. Veyrix uses the native Web Crypto API to generate a SHA-256 hash locally instead: + +```javascript +// Internal Utility Method +async function hashPassword(password) { + const msgBuffer = new TextEncoder().encode(password); + const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer); + const hashArray = Array.from(new Uint8Array(hashBuffer)); + return hashArray.map(b => b.toString(16).padStart(2, '0')).join(''); +} +``` + +## Threat model assumptions + +### 1. Physical security + +Veyrix relies completely on the local OS and browser profile. If an attacker gains physical, unlocked access to the device, or compromises the browser profile (e.g. via a malicious extension), the IndexedDB store is considered compromised. + +### 2. Cross-Site Scripting (XSS) + +Veyrix is an editor, not an evaluator. The Ace Editor parses content into Abstract Syntax Trees (ASTs) for highlighting — it does not execute code within the DOM. DOM string interpolations are secured via native `textContent` mappings. + +### 3. Cloud anonymity + +Firebase interactions use `signInAnonymously()`. Data is tied to a temporary, anonymous session UID. Firebase Security Rules are assumed to enforce read/write access correctly based on the snippet UID, but shared URLs are considered semi-public unless protected with the SHA-256 password hash described above. diff --git a/src/veyrix/usage-guide.md b/src/veyrix/usage-guide.md @@ -0,0 +1,41 @@ +--- +label: Usage Guide +icon: checklist +order: 590 +--- + +# Comprehensive Usage Guide + +How to operate Veyrix IDE effectively — file management, keyboard shortcuts, versioning, and sharing. + +## 1. Managing files + +**Creating a new file** — click the `+` icon in the sidebar (or the floating button on mobile). Type your desired filename including the extension (e.g. `script.js`, `index.html`, `Dockerfile`). Veyrix auto-detects the language from the extension for syntax highlighting. Files without an extension are allowed. + +**Importing an existing file** — click the Open File icon (folder with up arrow) in the top navigation bar, or press `Ctrl+O`. Select any valid text, configuration, or code file. Binary files (images, compiled `.exe` files) are rejected. + +**Renaming or deleting** — hover over any file in the left sidebar and click the three-dots (`...`) icon. From the dropdown: Rename, Delete, or Download that specific file. + +## 2. Editing & formatting + +**Autosave & manual save** — Veyrix caches your typing to the local database 500ms after you stop typing. A blue dot next to the filename in the top bar indicates unsaved changes. Force a save any time with `Ctrl+S` or the floppy disk icon. + +**Code formatting (Prettier)** — press `Alt+Shift+F` to beautify code (fix indentation and spacing). Only supported for recognized web languages: HTML, CSS, JS/JSX, JSON, Markdown. + +## 3. Snapshots (local version history) + +Veyrix has a built-in "Time Machine" for your files. + +- **Save a snapshot** — click the bookmark icon top right; saves a frozen copy of your code at that moment +- **Limits** — max 5 snapshots per file; saving a 6th prompts you to permanently delete the oldest one +- **Restore** — click the clock icon to view history; clicking "Restore" on an older version immediately replaces your current editor content with the historical code + +## 4. Sharing code + +Click the Share icon to open the sharing modal. Three options: + +**Fast local share** — compresses your entire file into the URL; no data leaves your browser. Best for small snippets, since large files produce very long URLs. + +**Cloud share** — uploads your code to an anonymous, secure Firebase database and generates a short link. Can optionally be protected with a password (hashed client-side — see [Security & Threat Model](security.md)). + +**Share via device** — uses your phone or computer's native share menu (AirDrop, WhatsApp, Email, etc.) to send the raw text of your code. diff --git a/src/veyrix/veyrix-web.md b/src/veyrix/veyrix-web.md @@ -0,0 +1,40 @@ +--- +label: Veyrix Web (Multi-File) +icon: file-directory +order: 560 +--- + +# Veyrix Web (Multi-File IDE) + +Veyrix Web (`web.html`) is an advanced, multi-file environment built specifically for web development. Unlike the single-file main IDE, it uses a robust virtual file system with directory structures, multi-tab editing, and an integrated real-time preview window. + +## Isolated database (VeyrixWebFS) + +To prevent data collision with the main IDE, Veyrix Web uses a completely separate IndexedDB named `VeyrixWebFS`. It tracks full relative paths (e.g. `/css/style.css`) rather than flat IDs, enabling a true folder hierarchy. + +```typescript +// VFS Node Representation +interface VFSNode { + path: string; // Absolute virtual path + type: string; // "file" or "folder" + content: string; // String payload or Base64 URI + isBase64: boolean; // Flags binary image assets +} +``` + +## Live preview engine + +The core of the Web IDE is the `PreviewEngine`. Because all files live inside IndexedDB, standard relative HTML links (like `<link rel="stylesheet" href="style.css">`) fail natively inside an isolated iframe — the engine intercepts and resolves these on the fly. + +**AST parsing & injection** — when rendering, the engine intercepts your `/index.html` file and uses the browser's native `DOMParser` API to scan the DOM for external scripts, styles, and image tags. + +**Virtual path resolution** — using `PathUtils.resolve()`, it computes the absolute virtual path of each linked asset, retrieves its content from the VFS, and transforms it: `<link>` tags become inline `<style>` tags, and `<script src>` tags become inline execution blocks. + +**Blob srcdoc rendering** — the compiled master HTML string is injected directly into the iframe's `srcdoc` attribute. This entirely bypasses cross-origin requests, eliminates network latency, and keeps processing fast and 100% offline. + +## Workspace export (ZIP) + +Unlike the main IDE (flat single files), Veyrix Web lets you export your entire workspace architecture. + +- **Combine HTML** — leverages the PreviewEngine to bundle all CSS, JavaScript, and Base64 images into a single monolithic `index.html`. Good for quick sharing or embedding in systems that don't support multi-file directories. +- **ZIP archive export** — dynamically loads the `JSZip` library only when requested, maps over the virtual file system, constructs a standard directory structure, and outputs a downloadable `.zip` preserving all relative paths and binary formats. diff --git a/src/whatsapp-logger/connect-whatsapp.md b/src/whatsapp-logger/connect-whatsapp.md @@ -0,0 +1,17 @@ +--- +label: 3. Connect WhatsApp +order: 860 +--- + +# Step 3: Connect WhatsApp + +1. Open your Render URL (`https://your-app.onrender.com`) in a browser. +2. Log in with the `AUTH_USER` / `AUTH_PASS` you set in Render. +3. You'll see a **QR code**. +4. On your phone, open WhatsApp: + - **iOS**: Settings → Linked Devices + - **Android**: three dots → Linked Devices +5. Tap **Link a Device** and scan the QR code. +6. The page refreshes and shows **"System Operational"** — your backend is now listening. + +Continue to [Setup the Frontend](setup-frontend.md). diff --git a/src/whatsapp-logger/deploy-backend.md b/src/whatsapp-logger/deploy-backend.md @@ -0,0 +1,24 @@ +--- +label: 2. Deploy Backend +order: 870 +--- + +# Step 2: Deploy Backend (The Listener) + +1. **Fork the repository** to your own GitHub account: [WhatsApp-Logger-Self-Hosted-](https://github.com/notamitgamer/WhatsApp-Logger-Self-Hosted-) +2. Log in to [Render](https://render.com/). +3. Click **New +** → **Web Service**. +4. Connect your forked repository. +5. **Runtime**: select **Docker**. +6. Add the following **environment variables** under "Advanced": + +| Variable | Value | +|---|---| +| `FIREBASE_SERVICE_ACCOUNT` | The entire content of the service-account JSON file downloaded in the Firebase step | +| `AUTH_USER` | A username of your choice (e.g. `admin`) | +| `AUTH_PASS` | A strong password — this locks your logger | + +7. Click **Create Web Service**. +8. Wait for deployment to finish. Render gives you a URL like `https://your-app.onrender.com`. + +Continue to [Connect WhatsApp](connect-whatsapp.md). diff --git a/src/whatsapp-logger/firebase-setup.md b/src/whatsapp-logger/firebase-setup.md @@ -0,0 +1,59 @@ +--- +label: 1. Firebase Setup +order: 880 +--- + +# Step 1: Firebase Setup (The Database) + +1. Go to the [Firebase Console](https://console.firebase.google.com/) and create a new project. + +## Create the database + +1. Navigate to **Firestore Database** in the sidebar. +2. Click **Create Database**. +3. Select a location (e.g. `nam5` or `eur3`). +4. Start in **Production Mode**. + +## Set security rules + +Go to the **Rules** tab in Firestore and replace the rules with the following. This allows anyone to read, but only your backend (via the Admin SDK) can write: + +```javascript +rules_version = '2'; +service cloud.firestore { + match /databases/{database}/documents { + match /{document=**} { + // 1. Allow Read: Essential for your HTML page to fetch chats. + allow read: if true; + + // 2. Allow Update: Enables the "Rename Chat" feature from the frontend. + // This allows updating existing documents (like changing the name) + // but prevents creating NEW documents or Deleting them. + allow update: if true; + + // 3. Block Create/Delete: Only the Backend (Render) can create new messages + // or delete them. This prevents random people from injecting fake chats. + allow create, delete: if false; + } + } +} +``` + +## Get backend credentials (service account) + +1. Go to **Project Settings** (gear icon) → **Service accounts**. +2. Click **Generate new private key**. +3. This downloads a `.json` file. + +!!!danger Keep this safe +This file grants admin access to your database. You'll paste its contents into a Render environment variable in the next step — never commit it to a public repo. +!!! + +## Get frontend configuration + +1. Go to **Project Settings** → **General**. +2. Scroll to "Your apps" and click the **Web (`</>`)** icon. +3. Register the app (nickname: "Logger Frontend"). +4. Copy the `firebaseConfig` object (API key, project ID, etc.) — you'll need it for `index.html` later. + +Continue to [Deploy the Backend](deploy-backend.md). diff --git a/src/whatsapp-logger/index.md b/src/whatsapp-logger/index.md @@ -0,0 +1,47 @@ +--- +label: WhatsApp Logger +icon: comment-discussion +order: 900 +--- + +# WhatsApp Logger (Self-Hosted) + +A privacy-focused, self-hosted WhatsApp archiving tool. It captures messages — including deleted ones — via a linked device connection and stores them in your own Firebase Firestore database. + +!!!warning Update to v4.1.7 +Earlier versions could get stuck in a reconnect loop (Status 428) due to a deprecated `printQRInTerminal` setting in Baileys. This is fixed in v4.1.7, along with QR code rendering now working directly on the Express web interface instead of the broken terminal output. +!!! + +!!!success Is this safe to use? +Yes. WhatsApp bans accounts for *sending* spam or unauthorized automated messages — this tool is a **100% passive, read-only listener**. It connects using the official Multi-Device WebSocket protocol, the same way linking a second browser to WhatsApp Web works. Since it doesn't interact with anyone, there's no risk of being reported. +!!! + +## Features + +- **Anti-Delete** — messages are logged instantly, so they're preserved even if the sender deletes them +- **Privacy first** — you host the backend and database; no third-party servers touch your data +- **Secure access** — the frontend is password-protected against your own backend +- **Search & filter** — search by content or filter by date +- **Export** — download chat logs as `.txt` files +- **Offline ready** — IndexedDB caching lets you read logs without an internet connection + +## Recommended setup + +- Install the web app as a **PWA** after publishing it, for better security and a native feel +- Enable **PIN or biometric authentication** inside the web app (Settings) + +## Get started + +- [Prerequisites & Architecture](prerequisites.md) +- [Step 1 — Firebase Setup](firebase-setup.md) +- [Step 2 — Deploy the Backend](deploy-backend.md) +- [Step 3 — Connect WhatsApp](connect-whatsapp.md) +- [Step 4 — Setup the Frontend](setup-frontend.md) +- [Step 5 — Usage](usage.md) +- [Step 6 — Keep it Alive](keep-alive.md) +- [Troubleshooting](troubleshooting.md) +- [Roadmap](roadmap.md) + +## Disclaimer + +This tool is for personal archiving purposes. Using it to log conversations without consent may violate privacy laws in your jurisdiction. The author is not responsible for misuse. diff --git a/src/whatsapp-logger/keep-alive.md b/src/whatsapp-logger/keep-alive.md @@ -0,0 +1,16 @@ +--- +label: 6. Keep it Alive +order: 830 +--- + +# Step 6: Keep it Alive (UptimeRobot) + +Render's free tier spins down after inactivity. To keep your logger running 24/7: + +1. Create a free account on [UptimeRobot](https://uptimerobot.com/). +2. Click **Add New Monitor**. +3. **Monitor Type**: HTTP(s) +4. **Friendly Name**: WhatsApp Logger +5. **URL (or IP)**: `https://your-app.onrender.com/ping` (make sure to include `/ping`) +6. **Monitoring Interval**: 5 minutes +7. Click **Create Monitor**. diff --git a/src/whatsapp-logger/prerequisites.md b/src/whatsapp-logger/prerequisites.md @@ -0,0 +1,23 @@ +--- +label: Prerequisites +order: 890 +--- + +# Prerequisites + +Before you start, make sure you have the following: + +1. A **GitHub** account +2. A **Render** account (free tier works) +3. A **Firebase** account (free Spark plan works) +4. A **WhatsApp** account on your phone +5. An **UptimeRobot** account (free) + +## How it fits together + +- **Backend (Render + Docker)** — runs the Baileys WhatsApp listener, authenticates the frontend, and writes messages to Firestore +- **Database (Firebase Firestore)** — stores your chat logs +- **Frontend (`index.html`)** — a single static file you host anywhere (Firebase Hosting, GitHub Pages, Netlify, Vercel) that reads from Firestore and talks to your Render backend +- **UptimeRobot** — pings your Render backend every 5 minutes so the free tier doesn't spin down from inactivity + +Continue to [Firebase Setup](firebase-setup.md). diff --git a/src/whatsapp-logger/roadmap.md b/src/whatsapp-logger/roadmap.md @@ -0,0 +1,46 @@ +--- +label: Roadmap +icon: milestone +order: 810 +--- + +# Roadmap: Media Upgrade & Security Enhancements + +!!!warning In progress +This work lives on a separate branch. **Do not sync your fork with it yet** — it may break the logger until it's finished. +!!! + +Firebase's free tier caps storage at 1GB, which isn't viable for media. The plan is to keep text messages in Firebase as-is, and offload images, videos, and voice messages to Hugging Face storage instead, fronted by a Cloudflare CDN. + +## Phase 1 — Architecture & infrastructure + +- Detect `imageMessage`, `videoMessage`, and `audioMessage` types in the Baileys listener +- Extract binary buffers with Baileys' `downloadMediaMessage` +- Push buffers to a Hugging Face dataset repo via the HF Hub API +- Serve media through a Cloudflare Pages + Workers CDN, so HF API tokens are never exposed to the frontend +- Store the resulting Cloudflare CDN URL, `mimeType`, and metadata in the existing Firestore `Messages` collection + +## Phase 2 — Backend (`index.js`) + +- Add dependencies for Hugging Face Hub uploads (`axios` or `fetch`) +- Expand the `messages.upsert` listener with conditional checks for media attachments +- Add an async upload utility that pushes buffers to Hugging Face and builds the Cloudflare CDN URL +- Extend the Firestore `set` operation with `mediaUrl`, `mediaType`, and `caption` (falling back to `text`) + +## Phase 3 — Frontend (`index.html`) + +- Update `renderMsgs` to check for `mediaUrl` and conditionally render `<img loading="lazy">`, `<video controls>`, or `<audio controls>` +- Keep media containers consistent with the existing Material Design 3 styling (12px border radius, surface container alignment) +- Rely on browser caching via Cloudflare CDN headers for media rather than storing raw files in IndexedDB or the service worker cache + +## Phase 4 — Security + +- Re-verify Firestore rules stay read-only/update-only safe with the new media metadata shape +- Ensure `escapeHTML` correctly sanitizes incoming media URLs to prevent XSS +- Add CSP headers on the frontend deployment to whitelist the specific Cloudflare subdomains used for media delivery + +## Phase 5 — Testing & deployment + +- Run the Docker container locally to confirm Baileys downloads/buffers large video files without crashing +- Verify the Cloudflare Worker proxies Hugging Face dataset URLs with correct CORS headers +- Push to GitHub and monitor Render build logs for the updated backend diff --git a/src/whatsapp-logger/setup-frontend.md b/src/whatsapp-logger/setup-frontend.md @@ -0,0 +1,38 @@ +--- +label: 4. Setup Frontend +order: 850 +--- + +# Step 4: Setup Frontend (The Viewer) + +1. Download `index.html` from the repository. +2. Open it in a text editor. +3. Find the configuration section (around line 675). Before editing, it looks like this: + +```javascript +const RENDER_BACKEND_URL = ""; + +// Firebase Config +const firebaseConfig = { + apiKey: "", + authDomain: "", + projectId: "", + storageBucket: "", + messagingSenderId: "", + appId: "" +}; +``` + +4. Fill in the details: + - `RENDER_BACKEND_URL` — your Render URL, e.g. `https://your-app.onrender.com` (**no trailing slash**) + - `firebaseConfig` — the keys you copied during [Firebase Setup](firebase-setup.md) + +## Deploy the frontend + +You can host this single file anywhere: + +- **Firebase Hosting** (recommended): `firebase init` → Hosting → select `public` directory → put `index.html` there → `firebase deploy` +- **GitHub Pages**: enable Pages in your repo settings +- **Netlify / Vercel**: drag and drop the folder containing `index.html` + +Continue to [Usage](usage.md). diff --git a/src/whatsapp-logger/troubleshooting.md b/src/whatsapp-logger/troubleshooting.md @@ -0,0 +1,16 @@ +--- +label: Troubleshooting +icon: alert +order: 820 +--- + +# Troubleshooting + +**"No chats found"** +: Send a message to the linked WhatsApp account to trigger the first log. + +**"Incorrect Credentials"** +: Make sure your Render backend is running, and that you're using the exact `AUTH_USER` / `AUTH_PASS` defined in Render's environment variables. + +**Chat shows a long ID (e.g. `1155...@lid`) instead of a phone number** +: Wait a few minutes — the backend automatically syncs contacts and updates the record with the real phone number. diff --git a/src/whatsapp-logger/usage.md b/src/whatsapp-logger/usage.md @@ -0,0 +1,16 @@ +--- +label: 5. Usage +order: 840 +--- + +# Step 5: Usage + +1. Navigate to your hosted frontend URL. +2. You'll see a login screen. +3. Enter the same `AUTH_USER` / `AUTH_PASS` configured on Render. +4. Once unlocked, your chats load from Firebase: + - **Sidebar** — chat list sorted by newest activity + - **Search** — filter contacts by name or phone number + - **Export** — download chat history as a `.txt` file + +Continue to [Keep it Alive](keep-alive.md).