aztomiq 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ph4n4n
+
+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,146 @@
+# ⚛️ AZtomiq
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![Style](https://img.shields.io/badge/style-Glassmorphism-blue)](https://aztomiq.vercel.app/)
+
+A high-performance, **privacy-first**, and ultra-modular multi-tool website framework. Built with a passion for simplicity and speed.
+
+[Live Demo](https://aztomiq.vercel.app/) • [Report Bug](https://github.com/ph4n4n/aztomiq/issues) • [Request Feature](https://github.com/ph4n4n/aztomiq/issues)
+
+### In production
+
+AZtomiq powers:
+
+- https://ztools.site — a full-scale utility tools platform
+
+---
+
+## 🌟 Why AZtomiq?
+
+AZtomiq isn't just another static site generator. It's an **Ecosystem** designed for building professional utility toolkits.
+
+- **⚛️ Atomic Architecture**: Every feature is a self-contained "Atom". Zero global dependencies, maximum portability.
+- **🛡️ Privacy by Design**: 100% Client-side processing. No data ever leaves the user's browser.
+- **🌍 Production Ready i18n**: Built-in multi-lingual support with atomic translation merging.
+- **⚡ Blazing Fast**: No heavy JS frameworks. Powered by Vanilla JS and optimized EJS templates.
+- **📱 Modern PWA**: Fully offline-capable with automated Service Worker generation.
+
+---
+
+## 🏗️ Core Architecture
+
+```text
+.
+├── bin/              # 🛠️ Main CLI entry point
+├── docs/             # 📚 Documentation & Guides
+├── scripts/          # ⚙️ Modular build logic (Pages, Assets, Cache)
+├── src/
+│   ├── assets/       # 🎨 Global Design System (CSS/JS)
+│   ├── data/         # 📊 Global site & category metadata
+│   ├── features/     # ⚛️ Atomic Tools (The heart of AZtomiq)
+│   ├── includes/     # 🧩 Reusable EJS components
+│   ├── locales/      # 🌍 System-wide translations
+│   ├── pages/        # 📄 Static landing & system pages
+│   └── templates/    # 🧬 SEO & PWA generators
+└── package.json
+```
+
+---
+
+## 🚀 Quick Start
+
+### 0. Prerequisites
+
+- **Node.js**: v18.0.0 or higher
+- **NPM**: v8.0.0 or higher
+- **Git**: For deployment
+
+### 1. Installation
+
+**Option A: Scaffolding a new project (Recommended)**
+
+```bash
+npx create-aztomiq my-awesome-app
+cd my-awesome-app
+npm install
+```
+
+**Option B: Manual Installation**
+
+```bash
+git clone https://github.com/ph4n4n/aztomiq.git
+cd aztomiq
+npm install
+```
+
+### 2. Development
+
+Start the watcher and local server:
+
+```bash
+npm run dev
+```
+
+### 3. Creating Your First Tool
+
+Use our CLI to scaffold a new feature instantly:
+
+```bash
+npm run aztomiq tool:create my-awesome-tool
+```
+
+### 4. Build for Production
+
+Generate the static site in the `dist/` folder:
+
+```bash
+npm run build
+```
+
+### 5. Deployment
+
+Ship it to GitHub Pages (configured in `global.yaml`):
+
+```bash
+npm run deploy
+```
+
+---
+
+## 📚 Documentation
+
+Dive deeper into how AZtomiq works:
+
+- [📂 **Project Structure**](./docs/STRUCTURE.md) - Understand the folder organization.
+- [⚛️ **Atomic Features**](./docs/FEATURES.md) - Deep dive into tool architecture.
+- [🛠️ **CLI Reference**](./docs/CLI.md) - Master the power of the `aztomiq` command.
+- [⚙️ **Development Guide**](./docs/DEVELOPMENT.md) - Rules and best practices for creating tools.
+- [📈 **Deployment Guide**](./docs/DEPLOYMENT.md) - How to ship to production.
+- [📜 **Project Changelog**](./docs/CHANGELOG.md) - Track the evolution of the framework.
+
+---
+
+## 🤝 Contribution
+
+We love contributors! If you have a cool tool idea:
+
+1. Fork the Project.
+2. Create your Feature Branch (`git checkout -b feature/AmazingTool`).
+3. Create your tool using `npm run aztomiq tool:create`.
+4. Commit your Changes.
+5. Push to the Branch.
+6. Open a Pull Request.
+
+---
+
+## 📜 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+<p align="center">
+  Built with ❤️ by the AZtomiq Team<br>
+  <i>"Fast. Simple. Atomic."</i>
+</p>

package/bin/aztomiq.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const { spawn } = require('child_process');
+const yaml = require('js-yaml');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const PROJECT_ROOT = process.cwd();
+const CORE_ROOT = path.join(__dirname, '..');
+
+const commands = {
+  build: async () => {
+    const force = args.includes('--force');
+    const obfuscate = args.includes('--obfuscate');
+    const cmdArgs = ['scripts/build.js'];
+    if (force) cmdArgs.push('--force');
+    if (obfuscate) cmdArgs.push('--obfuscate');
+    runNode(cmdArgs);
+  },
+  dev: async () => {
+    runNode(['scripts/build.js', '--dev'], () => {
+      runNode(['server.js']);
+    });
+  },
+  deploy: async () => {
+    runNode(['scripts/deploy.js']);
+  },
+  test: async () => {
+    const type = args[1] || 'all';
+    if (type === 'ui') {
+      runNode(['scripts/ui-test.js']);
+    } else {
+      runNpm(['run', 'test']);
+    }
+  },
+  status: async () => {
+    console.log('\n🔍  Scanning AZtomiq Ecosystem...');
+    const featuresDir = path.join(PROJECT_ROOT, 'src/features');
+    const testDir = path.join(PROJECT_ROOT, 'tests/features');
+    const dirs = await fs.readdir(featuresDir);
+
+    console.log('-----------------------------------------------------------------------------------');
+    console.log(`${'Feature ID'.padEnd(25)} | ${'Status'.padEnd(10)} | ${'Locales'.padEnd(10)} | ${'Tests'.padEnd(8)} | ${'Mode'}`);
+    console.log('-----------------------------------------------------------------------------------');
+
+    for (const id of dirs) {
+      const featPath = path.join(featuresDir, id);
+      if (!(await fs.stat(featPath)).isDirectory()) continue;
+
+      const toolYaml = path.join(featPath, 'tool.yaml');
+      if (!await fs.pathExists(toolYaml)) continue;
+
+      const config = yaml.load(await fs.readFile(toolYaml, 'utf8'));
+      const vi = await fs.pathExists(path.join(featPath, 'locales/vi.yaml'));
+      const en = await fs.pathExists(path.join(featPath, 'locales/en.yaml'));
+      const hasTest = (await fs.pathExists(testDir)) && (await fs.readdir(testDir)).some(f => f.startsWith(id));
+
+      const status = config.status === 'active' ? '✅ ACTIVE' : '🚧 DRAFT';
+      const locales = (vi ? 'VI ' : '   ') + (en ? 'EN' : '');
+      const test = hasTest ? '✓ YES' : '✗ NO';
+      const mode = (config.mode || 'std').toUpperCase();
+
+      console.log(`${id.padEnd(25)} | ${status.padEnd(10)} | ${locales.padEnd(10)} | ${test.padEnd(8)} | ${mode}`);
+    }
+    console.log('-----------------------------------------------------------------------------------\n');
+  },
+  analyze: async () => {
+    console.log('\n📊  Analyzing Tool Payload...');
+    let distFolder = 'dist';
+    let distAssets = path.join(PROJECT_ROOT, 'dist/assets/features');
+
+    if (!await fs.pathExists(distAssets)) {
+      distFolder = 'dist-dev';
+      distAssets = path.join(PROJECT_ROOT, 'dist-dev/assets/features');
+    }
+
+    if (!await fs.pathExists(distAssets)) {
+      console.error('❌ Build folder (dist/ or dist-dev/) not found. Please run "aztomiq build" first.');
+      return;
+    }
+
+    console.log(`📂  Target: ${distFolder}/`);
+    const tools = await fs.readdir(distAssets);
+    let totalSize = 0;
+
+    console.log('------------------------------------------------------------------');
+    console.log(`${'Tool ID'.padEnd(25)} | ${'CSS Size'.padEnd(12)} | ${'JS Size'.padEnd(12)} | ${'Total'}`);
+    console.log('------------------------------------------------------------------');
+
+    for (const tool of tools) {
+      const toolDir = path.join(distAssets, tool);
+      if (!(await fs.stat(toolDir)).isDirectory()) continue;
+
+      const cssFile = path.join(toolDir, 'style.css');
+      const jsFile = path.join(toolDir, 'script.js');
+
+      const cssSize = await fs.pathExists(cssFile) ? (await fs.stat(cssFile)).size : 0;
+      const jsSize = await fs.pathExists(jsFile) ? (await fs.stat(jsFile)).size : 0;
+      const sum = cssSize + jsSize;
+      totalSize += sum;
+
+      console.log(`${tool.padEnd(25)} | ${formatBytes(cssSize).padEnd(12)} | ${formatBytes(jsSize).padEnd(12)} | ${formatBytes(sum)}`);
+    }
+    console.log('------------------------------------------------------------------');
+    console.log(`${'TOTAL ECOSYSTEM SIZE'.padEnd(55)} | ${formatBytes(totalSize)}`);
+    console.log('------------------------------------------------------------------\n');
+  },
+  cleanup: async () => {
+    console.log('🧹 Cleaning up workspace...');
+
+    // 1. Remove dist folders
+    await fs.remove(path.join(PROJECT_ROOT, 'dist'));
+    await fs.remove(path.join(PROJECT_ROOT, 'dist-dev'));
+    console.log('✅ Removed dist/ and dist-dev/');
+
+    // 2. Identify and remove draft tools if requested
+    if (args.includes('--drafts')) {
+      const featuresDir = path.join(PROJECT_ROOT, 'src/features');
+      const dirs = await fs.readdir(featuresDir);
+      for (const id of dirs) {
+        const toolYamlPath = path.join(featuresDir, id, 'tool.yaml');
+        if (await fs.pathExists(toolYamlPath)) {
+          const config = yaml.load(await fs.readFile(toolYamlPath, 'utf8'));
+          if (config.status === 'draft') {
+            await fs.remove(path.join(featuresDir, id));
+            console.log(`🗑️  Deleted draft tool: ${id}`);
+          }
+        }
+      }
+    }
+    console.log('✨ Workspace is clean.\n');
+  },
+  version: async () => {
+    const type = args[1] || 'patch'; // patch, minor, major
+    const targetId = args[2]; // specific tool id or 'all'
+
+    const bump = (v, t) => {
+      let [ma, mi, pa] = v.split('.').map(Number);
+      if (t === 'major') ma++;
+      else if (t === 'minor') mi++;
+      else pa++;
+      if (t === 'major') mi = 0;
+      if (t === 'major' || t === 'minor') pa = 0;
+      return `${ma}.${mi}.${pa}`;
+    };
+
+    const featuresDir = path.join(PROJECT_ROOT, 'src/features');
+    const tools = await fs.readdir(featuresDir);
+
+    for (const id of tools) {
+      if (targetId && targetId !== 'all' && targetId !== id) continue;
+
+      const yamlPath = path.join(featuresDir, id, 'tool.yaml');
+      if (!await fs.pathExists(yamlPath)) continue;
+
+      const raw = await fs.readFile(yamlPath, 'utf8');
+      const config = yaml.load(raw);
+
+      if (!config.meta) config.meta = { version: '1.0.0' };
+      const oldV = config.meta.version || '1.0.0';
+      const newV = bump(oldV, type);
+
+      config.meta.version = newV;
+      await fs.writeFile(yamlPath, yaml.dump(config));
+      console.log(`🚀 ${id.padEnd(25)} : ${oldV} -> ${newV}`);
+    }
+  },
+  'tool:create': async () => {
+    const name = args[1];
+    if (!name) {
+      console.error('❌ Please specify a tool name. Example: aztomiq tool:create my-new-tool');
+      return;
+    }
+
+    const toolDir = path.join(PROJECT_ROOT, 'src/features', name);
+    if (await fs.pathExists(toolDir)) {
+      console.error(`❌ Tool "${name}" already exists at ${toolDir}`);
+      return;
+    }
+
+    console.log(`🚀 Creating new tool: ${name}...`);
+
+    await fs.ensureDir(toolDir);
+    await fs.ensureDir(path.join(toolDir, 'locales'));
+
+    const toolYaml = `id: ${name}
+category: utilities
+icon: box
+title_key: ${name}.title
+desc_key: ${name}.desc
+status: active
+link: /${name}/
+mode: standard
+meta:
+  version: 1.0.0
+`;
+    await fs.writeFile(path.join(toolDir, 'tool.yaml'), toolYaml);
+
+    const indexEjs = `<!-- title: <%= t('${name}.title') %> - AZtomiq -->
+<section class="tool-page-container">
+  <div class="tool-header">
+    <h1><i data-lucide="box"></i> <%= t('${name}.title') %></h1>
+    <p><%= t('${name}.desc') %></p>
+    <div class="tool-meta">
+      <span class="version-badge" id="open-changelog">v<%= toolConfig.meta.version %></span>
+    </div>
+  </div>
+
+  <div class="card tool-card">
+    <div class="input-group">
+      <label>Sample Input</label>
+      <input type="text" id="sample-input" placeholder="Type something...">
+    </div>
+    <button id="action-btn" class="btn-primary">Execute</button>
+    <div id="result-area" class="result-box muted">
+      Result will appear here...
+    </div>
+  </div>
+</section>
+
+<script src="<%= toolConfig._assets.js %>"></script>
+<link rel="stylesheet" href="<%= toolConfig._assets.css %>">
+`;
+    await fs.writeFile(path.join(toolDir, 'index.ejs'), indexEjs);
+
+    const styleCss = `.tool-card {
+  max-width: 600px;
+  margin: 2rem auto;
+  padding: 2rem;
+}
+.result-box {
+  margin-top: 1.5rem;
+  padding: 1rem;
+  background: var(--bg-hover);
+  border-radius: 8px;
+  border: 1px solid var(--border-color);
+  min-height: 50px;
+}
+`;
+    await fs.writeFile(path.join(toolDir, 'style.css'), styleCss);
+
+    const scriptJs = `document.addEventListener('DOMContentLoaded', () => {
+  const input = document.getElementById('sample-input');
+  const btn = document.getElementById('action-btn');
+  const result = document.getElementById('result-area');
+
+  btn.addEventListener('click', () => {
+    const val = input.value || 'No input';
+    result.textContent = 'You entered: ' + val;
+    result.classList.remove('muted');
+    console.log('[${name}] Action executed');
+  });
+});
+`;
+    await fs.writeFile(path.join(toolDir, 'script.js'), scriptJs);
+
+    const enYaml = `${name}:
+  title: "${name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, ' ')}"
+  desc: "Professional utility tool for ${name}."
+`;
+    const viYaml = `${name}:
+  title: "${name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, ' ')}"
+  desc: "Công cụ tiện ích chuyên nghiệp cho ${name}."
+`;
+    await fs.writeFile(path.join(toolDir, 'locales/en.yaml'), enYaml);
+    await fs.writeFile(path.join(toolDir, 'locales/vi.yaml'), viYaml);
+
+    console.log(`✅ Tool "${name}" created successfully!`);
+    console.log(`👉 Edit it at: src/features/${name}`);
+  }
+};
+
+if (!command || !commands[command]) {
+  console.log(`
+🛠️  AZtomiq CLI v${require('../package.json').version}
+
+Usage:
+  aztomiq <command> [options]
+
+Commands:
+  aztomiq dev             Start development server (Watcher + Node)
+  aztomiq build           Build for production (--force, --obfuscate)
+  aztomiq deploy          Deploy to public distribution repository
+  aztomiq status          Scan ecosystem health (Locales, Tests, Config)
+  aztomiq analyze         Analyze tool payloads and ecosystem size
+  aztomiq cleanup         Remove build artifacts (--drafts to delete draft tools)
+  aztomiq version <type> [id] Bump versions of tools (patch, minor, major)
+  aztomiq test            Run integrity and logic tests
+  aztomiq test ui         Run Puppeteer UI automation tests
+  aztomiq tool:create <id> Scaffold a new atomic tool
+  `);
+  process.exit(0);
+}
+
+commands[command]().catch(err => {
+  console.error('❌ Error executing command:', err);
+  process.exit(1);
+});
+
+function formatBytes(bytes, decimals = 2) {
+  if (bytes === 0) return '0 Bytes';
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
+}
+
+function runNode(args, cb) {
+  // Smart resolve: Priority 1: Current Project, Priority 2: Framework Core
+  let scriptPath = args[0];
+  const localScript = path.join(PROJECT_ROOT, scriptPath);
+  const coreScript = path.join(CORE_ROOT, scriptPath);
+
+  if (fs.existsSync(localScript)) {
+    args[0] = localScript;
+  } else if (fs.existsSync(coreScript)) {
+    args[0] = coreScript;
+    console.log(`[aztomiq] Running core script: ${scriptPath}`);
+  }
+
+  const proc = spawn('node', args, { stdio: 'inherit', cwd: PROJECT_ROOT });
+  proc.on('close', (code) => {
+    if (code === 0 && cb) cb();
+  });
+}
+
+function runNpm(args, cb) {
+  const proc = spawn('npm', args, { stdio: 'inherit', cwd: PROJECT_ROOT, shell: true });
+  proc.on('close', (code) => {
+    if (code === 0 && cb) cb();
+  });
+}

package/bin/create-aztomiq.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const projectName = process.argv[2] || 'my-aztomiq-site';
+const projectPath = path.resolve(process.cwd(), projectName);
+
+if (fs.existsSync(projectPath)) {
+  console.error(`❌ Directory "${projectName}" already exists.`);
+  process.exit(1);
+}
+
+console.log(`🚀 Creating a new AZtomiq project: ${projectName}...`);
+
+// 1. Create project folder
+fs.ensureDirSync(projectPath);
+
+// 2. Define Template Structure (Minimal)
+const templateDirs = [
+  'src/assets/css',
+  'src/assets/js',
+  'src/assets/images',
+  'src/data',
+  'src/features/hello-world/locales',
+  'src/includes',
+  'src/locales/en',
+  'src/locales/vi',
+  'src/pages',
+  'src/templates'
+];
+
+templateDirs.forEach(dir => fs.ensureDirSync(path.join(projectPath, dir)));
+
+// 3. Create Basic Files
+const packageJson = {
+  name: projectName,
+  version: '1.0.0',
+  scripts: {
+    "dev": "aztomiq dev",
+    "build": "aztomiq build",
+    "status": "aztomiq status"
+  },
+  dependencies: {
+    "@aztomiq/core": "latest"
+  }
+};
+fs.writeJsonSync(path.join(projectPath, 'package.json'), packageJson, { spaces: 2 });
+
+const globalYaml = `site:
+  title: "${projectName}"
+  description: "Built with AZtomiq"
+build:
+  locales: ["en", "vi"]
+  default_locale: "en"
+`;
+fs.writeFileSync(path.join(projectPath, 'src/data/global.yaml'), globalYaml);
+
+// 4. Create a Sample Tool
+const toolYaml = `id: hello-world
+category: general
+icon: smile
+status: active
+`;
+fs.writeFileSync(path.join(projectPath, 'src/features/hello-world/tool.yaml'), toolYaml);
+
+const toolEjs = `<h1>Hello World</h1>
+<p>Welcome to your new AZtomiq site!</p>
+`;
+fs.writeFileSync(path.join(projectPath, 'src/features/hello-world/index.ejs'), toolEjs);
+
+console.log(`\n✅ Project "${projectName}" initialized successfully!`);
+console.log(`👉 Next steps:`);
+console.log(`   cd ${projectName}`);
+console.log(`   npm install`);
+console.log(`   npm run dev`);

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "aztomiq",
+  "version": "1.0.0",
+  "description": "AZtomiq - A comprehensive A-Z multi-tool framework with atomic architecture",
+  "main": "scripts/build.js",
+  "bin": {
+    "aztomiq": "bin/aztomiq.js",
+    "create-aztomiq": "bin/create-aztomiq.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "src/includes",
+    "src/templates",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "aztomiq": "node bin/aztomiq.js",
+    "test": "node bin/aztomiq.js test",
+    "build:dev": "node bin/aztomiq.js build",
+    "build:force": "node bin/aztomiq.js build --force",
+    "build": "node bin/aztomiq.js build",
+    "dev": "node bin/aztomiq.js dev",
+    "deploy": "node bin/aztomiq.js deploy"
+  },
+  "keywords": [
+    "framework",
+    "tools",
+    "utility",
+    "calculator",
+    "ejs",
+    "pwa"
+  ],
+  "author": "ph4n4n",
+  "license": "MIT",
+  "dependencies": {
+    "body-parser": "^2.2.1",
+    "chokidar": "^5.0.0",
+    "cors": "^2.8.5",
+    "ejs": "^3.1.9",
+    "express": "^5.2.1",
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.1",
+    "marked": "^17.0.1"
+  },
+  "devDependencies": {
+    "clean-css-cli": "^5.0.0",
+    "html-minifier-terser": "^7.0.0",
+    "javascript-obfuscator": "^4.0.0",
+    "jsdom": "^27.3.0",
+    "puppeteer": "^24.33.1",
+    "terser": "^5.0.0",
+    "vitest": "^4.0.16",
+    "xml2js": "^0.6.2"
+  }
+}