mediaguru 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the **MediaGuru** project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.1.0] - 2026-06-02
+
+### Added
+* **Local HTTP REST API Server (`mediaguru server`)**: A standalone, zero-dependency REST service exposing QR generators, webpage screenshots, and config profiles over port `3000`.
+* **Playwright Screenshots & Renders**: Built-in screenshot and document rendering tools.
+* **Branding & Legal Docs**: Completed open-source repository templates including MIT `LICENSE`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `SECURITY.md`.
+
+---
+
+## [1.0.0] - 2026-06-02
+
+### Added
+* **Core Processing Engines**: PDF (merge, split, extract, compress), Image (resize, convert, watermark, local chroma background remover), QR Code, Tesseract OCR, and Text-to-Image templates.
+* **CLI Subcommands**: Commander commands mapping for `pdf`, `image`, `qr`, `ocr`, `screenshot`, `text2img`, `compress`, `batch`, `export`, and `config`.
+* **Interactive Mode**: Guided console wizard driven by `inquirer` for fluid terminal setups.
+* **Dynamic Plugin Registry**: Lifecycle hooks supporting runtime commander subcommand injections.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully receiving constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best for the overall community, not just the individual
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and unwelcome sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate, fair, and corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders at **safety@kontyra.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Internal Contribution Guidelines
+
+This repository contains the confidential, proprietary source code of **MediaGuru** (a Kontyra product). Access and contributions are strictly limited to authorized engineering staff.
+
+## 🔒 Security & Access Rules
+
+* **Confidentiality**: Never share the source code, configs, or test sandboxes with external parties.
+* **Accidental Exposure Guard**: Ensure that you never push this repository to public git hosts or publish it to the public npm registry. `package.json` is gated with `"private": true` to block accidental uploads.
+
+---
+
+## 🛠️ Local Development Setup
+
+1. **Clone the Repository**:
+   ```bash
+   git clone <private-repo-url>/mediaguru.git
+   cd mediaguru
+   ```
+
+2. **Install Dependencies & Browsers**:
+   ```bash
+   npm install
+   npx playwright install chromium
+   ```
+
+3. **Development Commands**:
+   * Build TypeScript: `npm run build`
+   * Typecheck: `npm run typecheck`
+   * Run tests: `npm test`
+   * Run browser tests: `npm run test:browser`
+
+---
+
+## 📐 Coding Conventions
+
+* **Pure TypeScript**: Avoid using `any`. Write strict, explicit TypeScript interfaces and type parameters.
+* **ES Modules**: Always include `.js` file extensions in your relative imports (e.g. `import { QrEngine } from './qr/index.js';`).
+* **Decoupled Architecture**: All core features must reside in a dedicated engine under `src/core/` and conform to pluggable interfaces to avoid code bloating.
+* **Spinner Feedback**: Always provide immediate, friendly terminal feedback utilizing `ora` loading animations and `chalk` colors for successful/failed outcomes.
+* **Branding Integrity**: Include the signature terminal footer `Powered by Kontyra` at the completion of command tasks.
+
+---
+
+## 📬 Internal PR Checklist
+
+Before merging into `main`, ensure that:
+1. `npm run build` compiles cleanly with **zero** typecheck errors.
+2. `npm test` and `npm run test:browser` pass all validation suites successfully.
+3. The codebase formats nicely conforming to our configuration guidelines.
+4. You have updated the `CHANGELOG.md` with your feature highlights.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kontyra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# MediaGuru Unified Toolkit
+
+**Powered by Kontyra**
+
+[![npm version](https://img.shields.io/npm/v/mediaguru.svg)](https://www.npmjs.com/package/mediaguru)
+[![GitHub release](https://img.shields.io/github/v/release/RayBen445/mediaguru)](https://github.com/RayBen445/mediaguru/releases)
+[![CI](https://github.com/RayBen445/mediaguru/actions/workflows/test.yml/badge.svg)](https://github.com/RayBen445/mediaguru/actions/workflows/test.yml)
+[![lint](https://github.com/RayBen445/mediaguru/actions/workflows/lint.yml/badge.svg)](https://github.com/RayBen445/mediaguru/actions/workflows/lint.yml)
+
+
+**MediaGuru** is a premium, developer-focused npm CLI and terminal toolkit designed to generate, convert, process, optimize, and extract data from documents and media. Built using pure TypeScript, ES Modules, Sharp, PDF-Lib, Tesseract, and Playwright, it delivers state-of-the-art results for everyday developer tasks.
+
+---
+
+## 🚀 Key Features
+
+* **Interactive Mode**: Simply run `mediaguru` to launch a step-by-step terminal wizard.
+* **PDF Engine**: Convert Markdown/HTML to PDF via headless browser, and merge, split, extract, or compress PDFs.
+* **Image Processor**: Fast resizing, watermarking, format conversion, and extensible solid boundary background removal.
+* **OCR Text Extractor**: Convert images to text with direct TXT, Markdown, or JSON exporting.
+* **Playwright Screenshotter**: Capture responsive website layouts (with mobile emulation & full-page scroll height options).
+* **Text-to-Image Creator**: Generate stunning, visually polished social card assets, posters, quotes, and header banners.
+* **Folder Compressor**: Compress images or entire assets directories, showing file space statistics.
+* **Batch Operations**: Glob-expanded batch runs for file conversions and PDF compilation.
+* **Extensible Architecture**: Highly decoupled design allowing plugins to dynamically add custom commander actions.
+
+---
+
+## 📦 Installation & Setup
+
+Clone the repository and install dependencies:
+
+```bash
+cd mediaguru
+npm install
+npx playwright install chromium
+```
+
+To build and compile:
+
+```bash
+npm run build
+```
+
+Link command globally (optional):
+
+```bash
+npm link
+```
+
+---
+
+## 🛠️ CLI Command Reference
+
+MediaGuru registers `mediaguru` and `mguru` binary aliases.
+
+### 1. Interactive Mode
+```bash
+mediaguru
+```
+*(Launches Inquirer wizard menu)*
+
+### 2. PDF Tools
+```bash
+# Markdown / HTML compilation
+mediaguru pdf notes.md
+mediaguru pdf invoice.html
+
+# PDF Operations
+mediaguru pdf merge a.pdf b.pdf c.pdf
+mediaguru pdf split report.pdf
+mediaguru pdf extract report.pdf
+mediaguru pdf compress report.pdf
+```
+
+### 3. Image Tools
+```bash
+mediaguru image resize photo.jpg 800x600
+mediaguru image convert photo.png webp
+mediaguru image watermark image.jpg logo.png
+mediaguru image remove-bg photo.jpg
+```
+
+### 4. QR Generator
+```bash
+mediaguru qr https://kontyra.com
+mediaguru qr https://kontyra.com --svg
+mediaguru qr https://kontyra.com --size 500
+```
+
+### 5. OCR Engine
+```bash
+mediaguru ocr receipt.jpg
+mediaguru ocr receipt.jpg --export markdown
+```
+
+### 6. Screenshot Engine
+```bash
+mediaguru screenshot https://example.com
+mediaguru screenshot https://example.com --full-page
+mediaguru screenshot https://example.com --mobile
+```
+
+### 7. Text-to-Image Creator
+```bash
+mediaguru text2img "Welcome to Kontyra"
+mediaguru text2img "Code is poetry" --theme glass --type quote --author "Developer"
+```
+
+### 8. Compression
+```bash
+mediaguru compress photo.jpg
+mediaguru compress ./assets
+```
+
+### 9. Batch Processing
+```bash
+mediaguru batch "images/*.png" --convert webp
+mediaguru batch "docs/*.md" --pdf
+```
+
+### 10. Data Exporter & Configs
+```bash
+# Export system settings
+mediaguru export json
+mediaguru export markdown
+mediaguru export csv
+
+# Config panel
+mediaguru config
+```
+
+---
+
+## ⚙️ Configuration Profile
+
+Configuration is stored in `~/.mediagururc.json`. 
+
+* **Default Image Format**: Format used for resizes and text-to-image (`webp`, `png`, `jpg`, `jpeg`).
+* **PDF Rendering Engine**: Output compiler (`playwright`, `local`).
+* **Compression Quality**: Percent quality for sharp operations (`1-100`).
+* **Screenshot Resolution**: Standard resolution width/height (`e.g., 1280x720`).
+* **Output Folder**: Destination for processed files.
+
+---
+
+## 🔌 Extensible Plugin Architecture
+
+MediaGuru defines an extensible plugin framework. You can register custom modules with lifecycle hooks:
+
+```typescript
+import { IMediaGuruPlugin } from './plugins/index.js';
+
+const MyAiPlugin: IMediaGuruPlugin = {
+  name: 'mediaguru-ai-generator',
+  version: '1.0.0',
+  description: 'AI Image & Transcription Module',
+  
+  async beforeCommand(commandName, args) {
+    console.log(`Command ${commandName} is starting...`);
+  },
+  
+  registerCustomCommands(program) {
+    program
+      .command('ai-generate')
+      .description('Generate images using AI model endpoints')
+      .argument('<prompt>', 'Prompt for image generation')
+      .action(async (prompt) => {
+        console.log(`Generating AI graphics for prompt: "${prompt}"...`);
+      });
+  }
+};
+```
+
+---
+
+## 📝 Verification Tests
+Run the automated test suite to verify the core engines:
+
+```bash
+npm run build
+npm test
+```
+
+Outputs will be saved in the `./test_sandbox` folder.
+
+---
+
+### Terminal Footer Branding
+
+```text
+Powered by Kontyra
+```

package/RELEASE.md

@@ -0,0 +1,38 @@
+# Release Management Guide
+
+MediaGuru is a **Kontyra** private enterprise product and follows semantic versioning for stable, internal deployment.
+
+## Semantic Versioning Rules
+
+- **PATCH** (`x.y.Z`): bug fixes and non-breaking maintenance.
+- **MINOR** (`x.Y.z`): new backward-compatible features.
+- **MAJOR** (`X.y.z`): breaking API or behavior changes.
+
+## Release Workflow
+
+1. Ensure `main` is stable and CI compiles cleanly (`npm run build`).
+2. Run standard version updates or tag updates.
+3. Push commit + tag (`git push --follow-tags`) to the private Git host.
+4. Tag push triggers private enterprise automated workflow verifications:
+   - validates version/tag consistency
+   - runs tests and offline package validation
+   - updates changelog ledger
+   - generates private Release notes
+5. Publish from internal Release events.
+
+## Secure Private Publishing
+
+* **Private Registry**: Deployment is strictly published to Kontyra's private, authenticated enterprise registry.
+* **Accidental Publish Guard**: The configuration contains a `"private": true` block in `package.json`. If you attempt to run `npm publish` to the public npm registry, npm will immediately block the upload.
+* **Pre-publish Checks**:
+  - TypeScript compilation and typechecks (`npm run build` & `npm run typecheck`)
+  - Standalone REST API router testing
+  - Offline engine validation suite execution
+  - Playwright browser automation dry-run
+* Never publish manually from unverified branches.
+
+## Branch Strategy
+
+- `main`: production-ready.
+- `dev`: integration branch for upcoming releases.
+- `feature/*`: isolated feature work.

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+We actively provide security updates and patches for the following versions of **MediaGuru**:
+
+| Version | Supported |
+| --- | --- |
+| `1.x.x` | Yes (Active) |
+| `< 1.0.0` | No |
+
+## Reporting a Vulnerability
+
+We take the security of our command-line tools and web-automation scripts extremely seriously. If you identify a vulnerability or security flaw, please do **NOT** open a public issue on GitHub.
+
+Instead, please report security vulnerabilities directly to our team:
+* **Email**: **security@kontyra.com**
+
+Please include as much of the following details as possible to help us investigate:
+1. Clear description of the vulnerability and its potential impact.
+2. Step-by-step instructions or test scripts to reproduce the issue locally.
+3. System environment parameters (e.g. Node version, OS version).
+
+We will acknowledge receipt of your report within **24 hours** and aim to provide a resolved security patch within **7 business days**.

package/bin/mediaguru.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/cli/interactive.d.ts

@@ -0,0 +1 @@
+export declare function launchInteractive(): Promise<void>;