npm - @artilingo/artiframe-cli - Versions diffs - 1.0.0 - Mend

@artilingo/artiframe-cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/assets/logo.png +0 -0
package/assets/logo.svg +22 -0
package/assets/logo.webp +0 -0
package/assets/logo@0.5x.png +0 -0
package/assets/logo@0.75x.png +0 -0
package/assets/logo@1.5x.png +0 -0
package/assets/logo@2x.png +0 -0
package/assets/logo@3x.png +0 -0
package/assets/logo@4x.png +0 -0
package/bin/artiframe.js +57 -0
package/bin/artiframe.php +45 -0
package/core-stubs/app/ApiControl.php +81 -0
package/core-stubs/app/Database.php +69 -0
package/core-stubs/app/DotEnv.php +63 -0
package/core-stubs/app/R2Manager.php +130 -0
package/core-stubs/app/ViewControl.php +24 -0
package/core-stubs/bin/SystemMethod.php +271 -0
package/core-stubs/bin/ViewMethod.php +354 -0
package/core-stubs/docs/de.html +951 -0
package/core-stubs/docs/en.html +952 -0
package/core-stubs/docs/es.html +947 -0
package/core-stubs/docs/fr.html +850 -0
package/core-stubs/docs/tr.html +951 -0
package/core-stubs/public/assets/css/components/footer.css +0 -0
package/core-stubs/public/assets/css/components/header.css +0 -0
package/core-stubs/public/assets/css/components/mobilenav.css +0 -0
package/core-stubs/public/assets/css/components/sidebar.css +0 -0
package/core-stubs/public/assets/css/components/theme-modal.css +0 -0
package/core-stubs/public/assets/css/root/app.css +61 -0
package/core-stubs/public/assets/js/components/header.js +0 -0
package/core-stubs/public/assets/js/components/mobilenav.js +0 -0
package/core-stubs/public/assets/js/components/sidebar.js +0 -0
package/core-stubs/public/assets/js/components/theme-modal.js +0 -0
package/core-stubs/public/assets/js/root/app.js +30 -0
package/core-stubs/public/includes/footer.php +5 -0
package/core-stubs/public/includes/head.php +26 -0
package/core-stubs/public/includes/header.php +5 -0
package/core-stubs/public/includes/mobilenav.php +5 -0
package/core-stubs/public/includes/sidebar.php +5 -0
package/core-stubs/public/includes/theme-modal.php +5 -0
package/core-stubs/readme/de.md +29 -0
package/core-stubs/readme/en.md +29 -0
package/core-stubs/readme/es.md +29 -0
package/core-stubs/readme/fr.md +29 -0
package/core-stubs/readme/tr.md +29 -0
package/package.json +49 -0
package/scripts/postinstall.js +21 -0
package/src/App.php +266 -0
package/src/Commands/MakeApiCommand.php +71 -0
package/src/Commands/MakeClassCommand.php +88 -0
package/src/Commands/MakeViewCommand.php +95 -0
package/src/Commands/NewProjectCommand.php +633 -0
package/src/Commands/VersionCommand.php +92 -0
package/src/Lang/de.php +53 -0
package/src/Lang/en.php +53 -0
package/src/Lang/es.php +53 -0
package/src/Lang/fr.php +53 -0
package/src/Lang/tr.php +53 -0
package/src/Services/Safeguard.php +48 -0
package/src/Services/Translator.php +52 -0

package/core-stubs/docs/es.html ADDED Viewed

@@ -0,0 +1,947 @@
+<!DOCTYPE html>
+<html lang="es">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>ArtiFrame | Documentación Oficial para Desarrolladores</title>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --bg:          #0d1117;
+            --surface:     #161b22;
+            --surface-2:   #1c2128;
+            --border:      #30363d;
+            --text:        #e6edf3;
+            --muted:       #7d8590;
+            --green:       #009d6c;
+            --green-light: #00c88c;
+            --green-dim:   rgba(0,157,108,0.12);
+            --blue:        #58a6ff;
+            --yellow:      #e3b341;
+            --red:         #f85149;
+            --purple:      #bc8cff;
+            --code-bg:     #0d1117;
+            --sidebar-w:   280px;
+        }
+        *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+        html { scroll-behavior: smooth; }
+        body {
+            font-family: 'Inter', sans-serif;
+            background: var(--bg);
+            color: var(--text);
+            line-height: 1.75;
+            display: flex;
+        }
+        /* ---- SIDEBAR ---- */
+        .sidebar {
+            width: var(--sidebar-w);
+            background: var(--surface);
+            height: 100vh;
+            position: fixed;
+            top: 0; left: 0;
+            border-right: 1px solid var(--border);
+            overflow-y: auto;
+            padding: 28px 0 40px;
+            display: flex;
+            flex-direction: column;
+        }
+        .sb-logo {
+            padding: 0 22px 24px;
+            border-bottom: 1px solid var(--border);
+            margin-bottom: 16px;
+        }
+        .sb-logo strong {
+            font-size: 1.35rem;
+            font-weight: 700;
+            color: var(--green);
+            letter-spacing: -0.3px;
+        }
+        .sb-logo span {
+            display: block;
+            font-size: 0.75rem;
+            color: var(--muted);
+            margin-top: 3px;
+        }
+        .sb-cat {
+            padding: 16px 22px 6px;
+            font-size: 0.68rem;
+            text-transform: uppercase;
+            letter-spacing: 1.2px;
+            color: var(--green);
+            font-weight: 700;
+        }
+        .sidebar nav a {
+            display: block;
+            padding: 7px 22px;
+            font-size: 0.88rem;
+            color: var(--muted);
+            text-decoration: none;
+            border-left: 2px solid transparent;
+            transition: all .15s;
+        }
+        .sidebar nav a:hover,
+        .sidebar nav a.active {
+            color: var(--text);
+            background: var(--green-dim);
+            border-left-color: var(--green);
+        }
+        /* ---- MAIN ---- */
+        .content {
+            margin-left: var(--sidebar-w);
+            padding: 60px 70px 100px;
+            max-width: 1100px;
+            width: 100%;
+        }
+        /* ---- TYPOGRAPHY ---- */
+        h1 { font-size: 2.6rem; font-weight: 700; letter-spacing: -0.5px; margin-bottom: 16px; }
+        h1 span { color: var(--green); }
+        h2 {
+            font-size: 1.7rem; font-weight: 700;
+            margin: 72px 0 20px;
+            padding-bottom: 14px;
+            border-bottom: 1px solid var(--border);
+        }
+        h2 .tag { font-size: 0.65rem; padding: 3px 8px; border-radius: 4px; font-weight: 700; text-transform: uppercase; letter-spacing: .5px; vertical-align: middle; margin-left: 10px; }
+        h3 { font-size: 1.1rem; font-weight: 600; margin: 32px 0 12px; color: var(--green-light); display: flex; align-items: center; gap: 10px; }
+        p { color: var(--muted); margin-bottom: 16px; font-size: 0.97rem; }
+        strong { color: var(--text); }
+        ul, ol { margin: 0 0 16px 22px; color: var(--muted); font-size: 0.97rem; }
+        li { margin-bottom: 8px; }
+        a { color: var(--green-light); text-decoration: none; }
+        a:hover { text-decoration: underline; }
+        /* ---- LEAD ---- */
+        .lead { font-size: 1.05rem; color: var(--muted); margin-bottom: 0; max-width: 720px; }
+        /* ---- BADGES ---- */
+        .badge { font-size: 0.68rem; padding: 3px 8px; border-radius: 4px; font-weight: 700; text-transform: uppercase; letter-spacing: .5px; white-space: nowrap; }
+        .b-view   { background: rgba(88,166,255,.12); color: #58a6ff; border: 1px solid rgba(88,166,255,.3); }
+        .b-api    { background: rgba(188,140,255,.12); color: #bc8cff; border: 1px solid rgba(188,140,255,.3); }
+        .b-cli    { background: rgba(0,200,140,.12);   color: #00c88c; border: 1px solid rgba(0,200,140,.3); }
+        .b-core   { background: rgba(227,179,65,.12);  color: #e3b341; border: 1px solid rgba(227,179,65,.3); }
+        .b-sec    { background: rgba(248,81,73,.12);   color: #f85149; border: 1px solid rgba(248,81,73,.3); }
+        /* ---- CODE ---- */
+        pre {
+            background: var(--code-bg);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+            padding: 22px 24px;
+            overflow-x: auto;
+            margin: 18px 0 24px;
+            font-size: 0.875rem;
+            line-height: 1.6;
+        }
+        code { font-family: 'JetBrains Mono', 'Consolas', monospace; color: #e6edf3; }
+        .ic { /* inline code */
+            background: var(--surface-2);
+            padding: 2px 7px;
+            border-radius: 4px;
+            font-family: 'JetBrains Mono', monospace;
+            font-size: 0.85em;
+            color: var(--yellow);
+            border: 1px solid var(--border);
+        }
+        .kw { color: #ff7b72; }   /* keyword / php tag */
+        .fn { color: #d2a8ff; }   /* function name */
+        .st { color: #a5d6ff; }   /* string */
+        .cm { color: #8b949e; }   /* comment */
+        .nu { color: #79c0ff; }   /* number / bool */
+        .var { color: #ffa657; }  /* variable */
+        /* ---- CARDS ---- */
+        .card {
+            background: var(--surface);
+            border: 1px solid var(--border);
+            border-radius: 10px;
+            padding: 28px 32px;
+            margin-bottom: 20px;
+        }
+        .card.highlight { border-left: 3px solid var(--green); }
+        /* ---- ALERTS ---- */
+        .alert { padding: 18px 22px; border-radius: 8px; margin: 24px 0; border-left: 3px solid; font-size: 0.95rem; }
+        .a-info    { background: rgba(88,166,255,.08);  border-color: var(--blue);   color: #93c5fd; }
+        .a-warn    { background: rgba(227,179,65,.08);  border-color: var(--yellow); color: #fbbf24; }
+        .a-danger  { background: rgba(248,81,73,.08);   border-color: var(--red);    color: #fca5a5; }
+        .a-success { background: rgba(0,157,108,.08);   border-color: var(--green);  color: #6ee7b7; }
+        /* ---- RETURN TYPE ---- */
+        .ret { display: inline-block; font-size: 0.78rem; color: var(--green); font-family: 'JetBrains Mono', monospace; background: rgba(0,157,108,.12); padding: 3px 10px; border-radius: 4px; border: 1px solid rgba(0,157,108,.25); margin-bottom: 12px; }
+        /* ---- GRID ---- */
+        .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; margin-bottom: 24px; }
+        @media(max-width: 900px) { .grid-2 { grid-template-columns: 1fr; } }
+        /* ---- DIR TREE ---- */
+        .tree { background: var(--code-bg); border: 1px solid var(--border); border-radius: 8px; padding: 22px 24px; font-family: 'JetBrains Mono', monospace; font-size: 0.875rem; line-height: 1.9; white-space: pre; overflow-x: auto; }
+        .tree .dir { color: var(--blue); font-weight: 600; }
+        .tree .file { color: #e6edf3; }
+        .tree .note { color: #8b949e; }
+        .tree .warn { color: var(--yellow); }
+        .tree .safe { color: var(--green); }
+        /* ---- STEP LIST ---- */
+        .steps { counter-reset: step; list-style: none; margin: 0 0 24px; padding: 0; }
+        .steps li { counter-increment: step; display: flex; gap: 18px; margin-bottom: 20px; }
+        .steps li::before {
+            content: counter(step);
+            flex-shrink: 0;
+            width: 30px; height: 30px;
+            background: var(--green-dim);
+            border: 1px solid rgba(0,157,108,.3);
+            color: var(--green);
+            border-radius: 50%;
+            display: flex; align-items: center; justify-content: center;
+            font-weight: 700; font-size: 0.85rem;
+            margin-top: 2px;
+        }
+        /* ---- SIGNATURE TABLE ---- */
+        .sig-table { width: 100%; border-collapse: collapse; margin: 16px 0 24px; font-size: 0.87rem; }
+        .sig-table th { text-align: left; padding: 10px 14px; background: var(--surface-2); color: var(--muted); font-weight: 600; border-bottom: 1px solid var(--border); }
+        .sig-table td { padding: 10px 14px; border-bottom: 1px solid rgba(48,54,61,.5); vertical-align: top; }
+        .sig-table td:first-child { font-family: 'JetBrains Mono', monospace; color: var(--yellow); white-space: nowrap; }
+        .sig-table td:last-child { color: var(--muted); }
+        /* ---- SCROLL SPY ---- */
+        header#page-header { margin-bottom: 52px; }
+    </style>
+</head>
+<body>
+<!-- SIDEBAR -->
+<aside class="sidebar">
+    <div class="sb-logo">
+        <strong>ArtiFrame</strong>
+        <span>Documentación para Desarrolladores</span>
+    </div>
+    <nav>
+        <div class="sb-cat">Inicio</div>
+        <a href="#giris">Introducción y Filosofía</a>
+        <a href="#kurulum">Instalación</a>
+        <a href="#dizin">Estructura de Directorios</a>
+        <div class="sb-cat">Arquitectura</div>
+        <a href="#bootstrapper">Arquitectura Bootstrapper</a>
+        <a href="#kurallar">Conjunto de Reglas</a>
+        <div class="sb-cat">Herramienta CLI</div>
+        <a href="#cli-giris">Introducción a la CLI</a>
+        <a href="#cli-new">new</a>
+        <a href="#cli-view">make:view</a>
+        <a href="#cli-api">make:api</a>
+        <a href="#cli-class">make:class</a>
+        <a href="#cli-version">version</a>
+        <div class="sb-cat">Ayudantes de Vista (View Helpers)</div>
+        <a href="#vh-display">display()</a>
+        <a href="#vh-csrf">csrfField()</a>
+        <a href="#vh-dates">Funciones de Fecha</a>
+        <a href="#vh-format">Formato</a>
+        <a href="#vh-money">money()</a>
+        <div class="sb-cat">Ayudantes de Sistema (System Helpers)</div>
+        <a href="#sh-json">jsonResponse()</a>
+        <a href="#sh-csrf">verifyCsrf()</a>
+        <a href="#sh-sanitize">Sanitización</a>
+        <a href="#sh-request">HTTP y Petición</a>
+        <a href="#sh-security">Seguridad</a>
+        <div class="sb-cat">Seguridad de API</div>
+        <a href="#api-methods">Control de Métodos HTTP</a>
+        <a href="#api-cors">CORS</a>
+        <a href="#api-rate">Limitación de Tasa (Rate Limiting)</a>
+        <div class="sb-cat">Práctica</div>
+        <a href="#workflow">Flujo de Trabajo Completo</a>
+    </nav>
+</aside>
+<!-- MAIN CONTENT -->
+<main class="content">
+    <!-- ====== GİRİŞ ====== -->
+    <header id="page-header">
+        <h1>ArtiFrame <span>Documentación</span></h1>
+        <p class="lead">El framework de proyectos PHP nativos escalables administrados con cero dependencias externas, reglas estrictas y una poderosa CLI. Sin dependencias, libre del caos de paquetes de composer, un ecosistema ligero y rápido que le permite enfocarse en su lógica de negocio.</p>
+    </header>
+    <!-- ====== GİRİŞ & FELSEFE ====== -->
+    <section id="giris">
+        <h2>Introducción y Filosofía</h2>
+        <p>ArtiFrame se basa en el principio de <strong>"Convención sobre Configuración"</strong>. El poder de un framework no proviene de la riqueza de las herramientas que ofrece, sino de la coherencia del orden que establece.</p>
+        <div class="grid-2">
+            <div class="card highlight">
+                <h3>Cero Sobrecarga (Zero Overhead)</h3>
+                <p>Cero dependencias de paquetes de Composer, núcleo del framework o bibliotecas de terceros. Cada línea de código es suya; libre de inflamiento, libre de capas de abstracción innecesarias.</p>
+            </div>
+            <div class="card highlight">
+                <h3>La Seguridad es lo Primero</h3>
+                <p>La protección XSS, validación CSRF, sanitización contra inyección SQL y el control de métodos HTTP están integrados por defecto. La seguridad no es una opción, es un estándar.</p>
+            </div>
+            <div class="card highlight">
+                <h3>Conjunto Estricto de Reglas</h3>
+                <p>Un desarrollador junior recién incorporado al proyecto comprende la arquitectura <code class="ic">data-js</code> y la estructura de directorios en minutos. La armonía del equipo está garantizada a nivel del framework.</p>
+            </div>
+            <div class="card highlight">
+                <h3>CLI como Prioridad</h3>
+                <p>No se crean archivos de vista, API o clase manualmente. La CLI genera desde archivos stub, configura los enlaces de assets y mantiene el proyecto coherente.</p>
+            </div>
+        </div>
+        <div class="alert a-info">
+            <strong>ℹ️ Licencia AGPLv3:</strong> ArtiFrame es de código abierto. Los trabajos derivados que usted produzca pueden usarse libremente siempre que el código fuente permanezca abierto. El aviso de derechos de autor no puede eliminarse.
+        </div>
+    </section>
+    <!-- ====== KURULUM ====== -->
+    <section id="kurulum">
+        <h2>Instalación</h2>
+        <p>La CLI de ArtiFrame se instala como una herramienta PHP global. Se instala una vez, se usa en todos los proyectos.</p>
+        <h3>1. Instale la Herramienta CLI Globalmente</h3>
+        <pre><code><span class="cm"># Instalación global vía NPM</span>
+npm install -g @artilingo/artiframe-cli
+<span class="cm"># Verifique la instalación</span>
+artiframe</code></pre>
+        <h3>2. Shell Interactivo</h3>
+        <p>Simplemente escriba <code class="ic">artiframe</code> en la terminal y presione Enter. La CLI no se cierra; se abre un shell interactivo que escucha comandos continuamente:</p>
+        <pre><code>==================================================
+        ArtiFrame CLI Interactive Shell v1.0.0
+==================================================
+Type 'help' for commands, or 'exit' to quit.
+artiframe&gt; </code></pre>
+        <h3>3. Iniciar un Nuevo Proyecto</h3>
+        <pre><code>artiframe&gt; new mi-proyecto</code></pre>
+        <p>Este comando crea el directorio <code class="ic">mi-proyecto/</code> y copia todo el esqueleto estructural dentro de él: <code class="ic">app/</code>, <code class="ic">bin/</code>, <code class="ic">config/</code>, <code class="ic">public/</code>, <code class="ic">src/</code>, <code class="ic">.env.example</code> y la primera página <code class="ic">index.php</code>.</p>
+        <h3>4. Configuración del Entorno</h3>
+        <pre><code>cp .env.example .env</code></pre>
+        <p>Abra su archivo <code class="ic">.env</code> y rellene la información de la base de datos y la aplicación. Este archivo nunca entra al control de versiones.</p>
+        <div class="alert a-warn">
+            <strong>⚠️ Configuración del Servidor Web:</strong> Apunte la raíz del documento (document root) de Apache/Nginx a la carpeta <code class="ic">/public/</code>. Otros directorios nunca deben estar expuestos al exterior.
+        </div>
+    </section>
+    <!-- ====== DİZİN YAPISI ====== -->
+    <section id="dizin">
+        <h2>Estructura de Directorios</h2>
+        <p>La arquitectura generada cuando se inicia el proyecto; asegura una separación clara de responsabilidades (SoC).</p>
+        <div class="tree">
+<span class="dir">nombre-proyecto/</span>
+├── <span class="dir">app/</span>                     <span class="note"># Capa de infraestructura</span>
+│   ├── <span class="file">ViewControl.php</span>      <span class="note"># Bootstrapper para la Vista (página HTML)</span>
+│   ├── <span class="file">ApiControl.php</span>       <span class="note"># Bootstrapper para los endpoints API</span>
+│   ├── <span class="file">Database.php</span>         <span class="note"># Conexión de base de datos basada en PDO</span>
+│   ├── <span class="file">DotEnv.php</span>           <span class="note"># Lector de .env</span>
+│   └── <span class="file">R2Manager.php</span>        <span class="note"># Administrador de archivos Cloudflare R2</span>
+│
+├── <span class="dir warn">bin/</span>                     <span class="note"># ⚠️ Sistema central — no lo edite directamente</span>
+│   ├── <span class="file">SystemMethod.php</span>     <span class="note"># Ayudantes globales de API/Backend</span>
+│   ├── <span class="file">ViewMethod.php</span>       <span class="note"># Ayudantes globales de View/Frontend</span>
+│   └── <span class="dir">stubs/</span>               <span class="note"># Archivos de plantilla usados por la CLI</span>
+│       ├── view.stub
+│       ├── api-standart.stub
+│       ├── api-switch-case.stub
+│       └── class.stub
+│
+├── <span class="dir">config/</span>                  <span class="note"># Archivos de configuración</span>
+│   └── <span class="file">app-version.php</span>      <span class="note"># Constantes APP_VERSION y APP_ENV</span>
+│
+├── <span class="dir">public/</span>                  <span class="note"># ← El único directorio abierto del servidor web</span>
+│   ├── <span class="dir safe">assets/</span>
+│   │   ├── <span class="dir">css/</span>             <span class="note"># Archivos CSS específicos de la Vista</span>
+│   │   └── <span class="dir">js/</span>              <span class="note"># Archivos JS específicos de la Vista</span>
+│   ├── <span class="dir">includes/</span>            <span class="note"># Componentes compartidos</span>
+│   │   ├── head.php
+│   │   ├── header.php
+│   │   └── footer.php
+│   ├── <span class="dir">api/</span>                 <span class="note"># Archivos de endpoints API</span>
+│   └── <span class="file">index.php</span>            <span class="note"># Página principal</span>
+│
+├── <span class="dir">src/</span>                     <span class="note"># Lógica de negocio y clases</span>
+├── <span class="file">.env</span>                     <span class="note"># Variables de entorno (no entra en git)</span>
+├── <span class="file">.env.example</span>            <span class="note"># Plantilla — entra en git</span>
+└── <span class="file">guia.html</span>               <span class="note"># Este documento</span>
+        </div>
+        <div class="alert a-danger">
+            <strong>🚫 No toque el directorio bin/:</strong> Los archivos dentro de <code class="ic">bin/</code> son el núcleo del framework. No se añade lógica de negocio específica del proyecto aquí. Las clases y servicios que agregue van debajo de <code class="ic">src/</code>, los componentes de infraestructura van debajo de <code class="ic">app/</code>.
+        </div>
+    </section>
+    <!-- ====== BOOTSTRAPPER ====== -->
+    <section id="bootstrapper">
+        <h2>Arquitectura Bootstrapper <span class="tag b-core">Crítico</span></h2>
+        <p>ArtiFrame usa dos bootstrappers completamente independientes. Esta arquitectura previene inherentemente <strong>problemas de encabezados HTML y vulnerabilidades de seguridad</strong>.</p>
+        <div class="grid-2">
+            <div class="card highlight">
+                <h3><span class="badge b-view">View</span> ViewControl.php</h3>
+                <p>Se usa para páginas HTML (archivos view). Inicia sesión, carga <code class="ic">ViewMethod</code>.</p>
+                <pre><code><span class="cm">// public/perfil.php — HASTA ARRIBA, antes de imprimir HTML</span>
+<span class="kw">&lt;?php</span>
+<span class="fn">require_once</span> <span class="var">$_SERVER</span>[<span class="st">'DOCUMENT_ROOT'</span>]
+    . <span class="st">'/../app/ViewControl.php'</span>;
+<span class="kw">use</span> Bin\ViewMethod;
+<span class="kw">?&gt;</span>
+<span class="kw">&lt;!DOCTYPE html&gt;</span>
+...</code></pre>
+            </div>
+            <div class="card highlight">
+                <h3><span class="badge b-api">API</span> ApiControl.php</h3>
+                <p>Se usa para archivos de endpoints API. Establece el encabezado JSON, comprueba el método HTTP, carga <code class="ic">SystemMethod</code>.</p>
+                <pre><code><span class="cm">// public/api/usuario/obtener.php</span>
+<span class="kw">&lt;?php</span>
+<span class="cm">// $allowedMethods DEBE definirse antes del require</span>
+<span class="var">$allowedMethods</span> = [<span class="st">'GET'</span>];
+<span class="fn">require_once</span> <span class="var">$_SERVER</span>[<span class="st">'DOCUMENT_ROOT'</span>]
+    . <span class="st">'/../app/ApiControl.php'</span>;
+<span class="kw">use</span> Bin\SystemMethod;</code></pre>
+            </div>
+        </div>
+        <div class="alert a-danger">
+            <strong>🚫 ViewControl y ApiControl nunca se mezclan:</strong> Si ViewControl se requiere en un archivo de API, puede devolver un encabezado HTML en lugar de un encabezado JSON y corromper toda la respuesta de la API. Si ApiControl se requiere en una página HTML, la sesión no se inicia y la página se rompe.
+        </div>
+    </section>
+    <!-- ====== KURALLAR ====== -->
+    <section id="kurallar">
+        <h2>Conjunto de Reglas <span class="tag b-core">Estándar</span></h2>
+        <div class="card">
+            <h3>Regla 1: Arquitectura data-js <span class="badge b-sec">Crítico</span></h3>
+            <p>Los eventos de JavaScript nunca deben escucharse a través de un <code class="ic">class</code> o <code class="ic">id</code>. Estos son identificadores visuales / de estilo. Todas las interacciones de JS se manejan mediante el atributo <code class="ic">data-js</code>. Cuando el CSS elimina una clase, JavaScript nunca se rompe.</p>
+            <pre><code><span class="cm">&lt;!-- ❌ Anti-Patrón — no soportado --&gt;</span>
+&lt;button id="submitBtn" class="btn"&gt;Enviar&lt;/button&gt;
+<span class="cm">// JS: document.getElementById('submitBtn').addEventListener(...)</span>
+<span class="cm">&lt;!-- ✅ Estándar ArtiFrame --&gt;</span>
+&lt;button class="btn btn-primary" <span class="var">data-js</span>="login-submit"&gt;Enviar&lt;/button&gt;
+<span class="cm">// JS: document.querySelector('[data-js="login-submit"]').addEventListener(...)</span></code></pre>
+        </div>
+        <div class="card">
+            <h3>Regla 2: Arquitectura de Temas</h3>
+            <p>El modo Oscuro/Claro y los temas se administran a través de los atributos <code class="ic">data-theme</code> y <code class="ic">data-mode</code> de la etiqueta <code class="ic">&lt;html&gt;</code>. No se utilizan clases en el body.</p>
+            <pre><code><span class="cm">&lt;!-- Etiqueta de apertura HTML de la plantilla view.stub --&gt;</span>
+&lt;html lang="es" data-theme="default" data-mode="light"&gt;
+<span class="cm">/* Definición del tema en app.css */</span>
+html[data-theme="default"][data-mode="dark"] {
+    --bg-color: #0b0c0e;
+    --text-main: #ffffff;
+}
+html[data-theme="default"][data-mode="light"] {
+    --bg-color: #ffffff;
+    --text-main: #111111;
+}</code></pre>
+        </div>
+        <div class="card">
+            <h3>Regla 3: Flujo de Datos Seguro</h3>
+            <p>Cada dato que proviene de la base de datos se envuelve con <code class="ic">display()</code> antes de imprimirse en el DOM. Cada dato que llega a la API se limpia con <code class="ic">sanitizeString()</code> o <code class="ic">sanitizeInt()</code> antes de ser procesado.</p>
+        </div>
+        <div class="card">
+            <h3>Regla 4: Manejo de Errores con APP_ENV</h3>
+            <p>El valor de <code class="ic">APP_ENV</code> en el archivo <code class="ic">.env</code> determina la visibilidad del error. En Producción (Production), no se muestran mensajes de error al usuario.</p>
+            <pre><code><span class="cm">// config/app-version.php</span>
+define(<span class="st">'APP_ENV'</span>, (int)<span class="var">$_ENV</span>[<span class="st">'APP_ENV'</span>]); <span class="cm">// 1=Debug, 0=Production</span>
+<span class="kw">if</span> (APP_ENV === <span class="nu">1</span>) {
+    ini_set(<span class="st">'display_errors'</span>, <span class="nu">1</span>);
+    error_reporting(E_ALL);
+} <span class="kw">else</span> {
+    ini_set(<span class="st">'display_errors'</span>, <span class="nu">0</span>);
+}</code></pre>
+        </div>
+    </section>
+    <!-- ====== CLI GİRİŞ ====== -->
+    <section id="cli-giris">
+        <h2>Ecosistema CLI</h2>
+        <p>La CLI de ArtiFrame abre un shell interactivo cuando escribe <code class="ic">artiframe</code> en la terminal. Todos los comandos se ejecutan dentro de este shell. Los comandos también se pueden ejecutar de forma puntual.</p>
+        <pre><code><span class="cm"># Modo interactivo (recomendado)</span>
+artiframe
+artiframe&gt; make:view admin/usuarios.php
+<span class="cm"># Modo puntual (una sola vez)</span>
+artiframe make:view admin/usuarios.php</code></pre>
+    </section>
+    <!-- new -->
+    <section id="cli-new">
+        <h2><code>new</code> <span class="tag b-cli">Comando CLI</span></h2>
+        <p>Crea un nuevo proyecto ArtiFrame. Crea todo el esqueleto de directorios, los archivos bootstrapper y la página index inicial.</p>
+        <pre><code>artiframe&gt; <span class="fn">new</span> <span class="st">nombre-proyecto</span></code></pre>
+        <p>Estructura creada:</p>
+        <div class="tree" style="font-size:0.82rem; line-height:1.7">
+nombre-proyecto/
+├── app/ (ViewControl.php, ApiControl.php, Database.php, DotEnv.php)
+├── bin/ (SystemMethod.php, ViewMethod.php, stubs/)
+├── config/ (app-version.php)
+├── public/ (index.php, assets/, includes/, api/)
+├── src/
+├── .env.example
+└── guia.html
+        </div>
+    </section>
+    <!-- make:view -->
+    <section id="cli-view">
+        <h2><code>make:view</code> <span class="tag b-cli">Comando CLI</span></h2>
+        <p>Crea un nuevo archivo de página (view) y sus recursos CSS/JS específicos. Los recursos se vinculan automáticamente a la página y se aplica la invalidación de caché (cache-busting) con <code class="ic">?v=APP_VERSION</code>.</p>
+        <pre><code>artiframe&gt; <span class="fn">make:view</span> <span class="st">admin/usuarios.php</span></code></pre>
+        <p>Archivos creados:</p>
+        <pre><code><span class="cm">✔  public/admin/usuarios.php</span>
+<span class="cm">✔  public/assets/css/admin/usuarios.css</span>
+<span class="cm">✔  public/assets/js/admin/usuarios.js</span></code></pre>
+        <p>El archivo de vista creado viene con ViewControl requerido al principio, los includes head/header/footer añadidos, y los enlaces CSS/JS conectados con cache-busting.</p>
+    </section>
+    <!-- make:api -->
+    <section id="cli-api">
+        <h2><code>make:api</code> <span class="tag b-cli">Comando CLI</span></h2>
+        <p>Crea un archivo de endpoint API eligiendo una de las dos plantillas diferentes. En cada nuevo archivo de API, la variable <code class="ic">$allowedMethods</code> y el requerimiento de <code class="ic">ApiControl.php</code> ya vienen preparados.</p>
+        <div class="card">
+            <h3><span class="badge b-api">standart</span> — API de Acción Única</h3>
+            <p>Para endpoints que realizan un solo trabajo (iniciar sesión, enviar, borrar). La lógica de negocio se escribe directamente.</p>
+            <pre><code>artiframe&gt; <span class="fn">make:api</span> <span class="st">standart</span> <span class="st">api/auth/entrar.php</span></code></pre>
+            <pre><code><span class="kw">&lt;?php</span>
+<span class="var">$allowedMethods</span> = [<span class="st">'POST'</span>]; <span class="cm">// Aceptar solo POST</span>
+<span class="fn">require_once</span> <span class="var">$_SERVER</span>[<span class="st">'DOCUMENT_ROOT'</span>] . <span class="st">'/../app/ApiControl.php'</span>;
+<span class="kw">use</span> Bin\SystemMethod;
+<span class="cm">// Lógica de negocio aquí...</span>
+<span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'success'</span>], <span class="nu">200</span>);</code></pre>
+        </div>
+        <div class="card">
+            <h3><span class="badge b-api">switch-case</span> — API de Múltiples Acciones</h3>
+            <p>Una estructura que maneja operaciones CRUD para un módulo en un único endpoint. Qué acción se debe realizar se determina por el parámetro <code class="ic">action</code>.</p>
+            <pre><code>artiframe&gt; <span class="fn">make:api</span> <span class="st">switch-case</span> <span class="st">api/usuario/administrar.php</span></code></pre>
+            <pre><code><span class="kw">&lt;?php</span>
+<span class="var">$allowedMethods</span> = [<span class="st">'POST'</span>];
+<span class="fn">require_once</span> <span class="var">$_SERVER</span>[<span class="st">'DOCUMENT_ROOT'</span>] . <span class="st">'/../app/ApiControl.php'</span>;
+<span class="kw">use</span> Bin\SystemMethod;
+<span class="var">$action</span> = <span class="fn">sanitizeString</span>(<span class="var">$_POST</span>[<span class="st">'action'</span>] ?? <span class="st">''</span>);
+<span class="kw">switch</span> (<span class="var">$action</span>) {
+    <span class="kw">case</span> <span class="st">'create'</span>:
+        <span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'success'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Creado.'</span>], <span class="nu">200</span>);
+        <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="st">'update'</span>:
+        <span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'success'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Actualizado.'</span>], <span class="nu">200</span>);
+        <span class="kw">break</span>;
+    <span class="kw">case</span> <span class="st">'delete'</span>:
+        <span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'success'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Eliminado.'</span>], <span class="nu">200</span>);
+        <span class="kw">break</span>;
+    <span class="kw">default</span>:
+        <span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'error'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Acción no válida.'</span>], <span class="nu">400</span>);
+}</code></pre>
+        </div>
+    </section>
+    <!-- make:class -->
+    <section id="cli-class">
+        <h2><code>make:class</code> <span class="tag b-cli">Comando CLI</span></h2>
+        <p>Crea un nuevo archivo de clase PHP con el namespace y la estructura básica (boilerplate) preparados.</p>
+        <pre><code>artiframe&gt; <span class="fn">make:class</span> <span class="st">classes/EmailService.php</span></code></pre>
+    </section>
+    <!-- version -->
+    <section id="cli-version">
+        <h2><code>version</code> <span class="tag b-cli">Comando CLI</span></h2>
+        <p>Actualiza el número de versión en <code class="ic">config/app-version.php</code> de acuerdo a las reglas de versionamiento semántico (SemVer). Formato de versión: <strong>MAYOR.MENOR.PARCHE</strong></p>
+        <table class="sig-table">
+            <thead>
+                <tr><th>Comando</th><th>Descripción</th><th>Ejemplo</th></tr>
+            </thead>
+            <tbody>
+                <tr><td>version upgrade patch</td><td>Corrección de errores, mejora menor</td><td>1.2.3 → 1.2.4</td></tr>
+                <tr><td>version upgrade minor</td><td>Nueva característica compatible con versiones anteriores</td><td>1.2.3 → 1.3.0</td></tr>
+                <tr><td>version upgrade major</td><td>Cambio importante que rompe compatibilidad</td><td>1.2.3 → 2.0.0</td></tr>
+                <tr><td>version downgrade patch</td><td>Deshacer el último parche</td><td>1.2.4 → 1.2.3</td></tr>
+                <tr><td>version downgrade minor</td><td>Deshacer el último menor</td><td>1.3.0 → 1.2.0</td></tr>
+                <tr><td>version downgrade major</td><td>Deshacer el último mayor</td><td>2.0.0 → 1.0.0</td></tr>
+            </tbody>
+        </table>
+        <pre><code>artiframe&gt; <span class="fn">version</span> upgrade minor
+<span class="cm">✔  Versión actualizada a 1.2.0 → 1.3.0.</span></code></pre>
+    </section>
+    <!-- ====== VIEW HELPERS ====== -->
+    <section id="vh-display">
+        <h2>Ayudantes de Vista (View Helpers) — <code>display()</code> <span class="tag b-view">ViewMethod</span></h2>
+        <p>Aplica una <strong>protección XSS obligatoria</strong> mientras imprime datos provenientes de la base de datos o entradas del usuario al DOM. En lugar de lanzar un error en valores nulos o vacíos, devuelve un valor predeterminado.</p>
+        <span class="ret">string display(mixed $data, string $default = '')</span>
+        <div class="alert a-info" style="margin-top: 10px; margin-bottom: 24px; padding: 12px 20px;">
+            <strong>💡 Consejo: Uso de <code>$default</code></strong><br>
+            El segundo parámetro (<code>$default</code>) es el texto de rescate que se mostrará en pantalla cuando los datos que provienen de la base de datos estén vacíos (nulo, falso, cadena vacía). Por ejemplo, si utiliza <code>display($nombre, 'Anónimo')</code> para un usuario cuyo nombre no se ha introducido, su página presentará contenido significativo en lugar de horribles espacios en blanco.
+        </div>
+        <pre><code><span class="cm">&lt;!-- ❌ Inseguro — crea una vulnerabilidad XSS --&gt;</span>
+&lt;h1&gt;&lt;?= <span class="var">$user</span>[<span class="st">'nombre'</span>] ?&gt;&lt;/h1&gt;
+<span class="cm">&lt;!-- ✅ Uso Seguro de ArtiFrame --&gt;</span>
+&lt;h1&gt;&lt;?= <span class="fn">display</span>(<span class="var">$user</span>[<span class="st">'nombre'</span>], <span class="st">'Usuario Anónimo'</span>) ?&gt;&lt;/h1&gt;</code></pre>
+    </section>
+    <section id="vh-escapeurl">
+        <h2>Ayudantes de Vista (View Helpers) — <code>escapeUrl()</code> <span class="tag b-view">ViewMethod</span></h2>
+        <p>Se utiliza al insertar enlaces recibidos de los usuarios (como sitios web de perfil) dentro de un <code>&lt;a href="..."&gt;</code> o <code>&lt;img src="..."&gt;</code>. Neutraliza cargas útiles (payloads) maliciosas como <code>javascript:alert(1)</code> (XSS Almacenado) y evita la ejecución de código a través de enlaces.</p>
+        <span class="ret">string escapeUrl(string $url)</span>
+        <pre><code><span class="cm">&lt;!-- ❌ Inseguro — se puede filtrar código JS a través de la URL --&gt;</span>
+&lt;a href="&lt;?= <span class="var">$user</span>[<span class="st">'website'</span>] ?&gt;"&gt;Visitar Sitio&lt;/a&gt;
+<span class="cm">&lt;!-- ✅ Uso Seguro de ArtiFrame --&gt;</span>
+&lt;a href="&lt;?= <span class="fn">escapeUrl</span>(<span class="var">$user</span>[<span class="st">'website'</span>]) ?&gt;"&gt;Visitar Sitio&lt;/a&gt;</code></pre>
+    </section>
+    <section id="vh-csrf">
+        <h2>Ayudantes de Vista (View Helpers) — <code>csrfField()</code> <span class="tag b-view">ViewMethod</span></h2>
+        <p>Añade un campo de token oculto a los formularios HTML contra ataques CSRF. <strong>Es obligatorio su uso en todas las páginas que contengan formularios POST.</strong></p>
+        <span class="ret">string csrfField()</span>
+        <pre><code>&lt;form action="/api/guardar.php" method="POST"&gt;
+    &lt;?= <span class="fn">csrfField</span>() ?&gt;   <span class="cm">&lt;!-- Es obligatorio por seguridad --&gt;</span>
+    &lt;input type="text" name="nombre"&gt;
+    &lt;button type="submit" data-js="btn-guardar"&gt;Guardar&lt;/button&gt;
+&lt;/form&gt;</code></pre>
+    </section>
+    <section id="vh-dates">
+        <h2>Ayudantes de Vista (View Helpers) — Funciones de Fecha <span class="tag b-view">ViewMethod</span></h2>
+        <p>Procesa cadenas de fecha en formato <code class="ic">Y-m-d H:i:s</code> de la base de datos o valores de marca de tiempo (timestamp) de UNIX. Todas las salidas textuales están localizadas según el idioma (<code class="ic">tr</code>, <code class="ic">en</code>, <code class="ic">de</code>, <code class="ic">fr</code>, <code class="ic">es</code>).</p>
+        <table class="sig-table">
+            <thead><tr><th>Función</th><th>Ejemplo de Salida</th><th>Descripción</th></tr></thead>
+            <tbody>
+                <tr><td>day($date)</td><td>24</td><td>Solo día</td></tr>
+                <tr><td>month($date)</td><td>07</td><td>Solo mes (número)</td></tr>
+                <tr><td>year($date)</td><td>2026</td><td>Año</td></tr>
+                <tr><td>timeOnly($date)</td><td>14:30</td><td>Hora:Minuto</td></tr>
+                <tr><td>fulldate($date)</td><td>24.07.2026</td><td>Fecha completa</td></tr>
+                <tr><td>formatDate($date, $format)</td><td>24.07.2026 14:30</td><td>Formato personalizado</td></tr>
+                <tr><td>monthName($date, $lang)</td><td>Julio / July / Juli</td><td>Nombre del mes (según el idioma)</td></tr>
+                <tr><td>fulldateName($date, $lang)</td><td>24 de julio de 2026 / July 24, 2026</td><td>Fecha completa (con el nombre del mes, según el idioma)</td></tr>
+                <tr><td>timeAgo($date, $lang)</td><td>Hace 5 minutos / 5 minutes ago</td><td>Estilo de redes sociales (según el idioma)</td></tr>
+            </tbody>
+        </table>
+        <div class="alert a-info" style="margin-top: 0; margin-bottom: 24px;">
+            <strong>💡 Entendiendo los Parámetros: <code>$format</code> y <code>$lang</code></strong>
+            <ul style="margin-top: 10px; margin-bottom: 0;">
+                <li style="margin-bottom: 8px;"><strong><code>$format</code> (Formato):</strong> Se usa únicamente con la función <code>formatDate()</code>. Acepta letras de formato de fecha PHP estándar. (Ejemplo: <code>'d/m/Y'</code> ➔ 24/07/2026, o <code>'H:i'</code> ➔ 15:30). Permite crear su propio patrón de fecha cuando otras funciones preparadas (day, year, etc.) no son suficientes.</li>
+                <li style="margin-bottom: 0;"><strong><code>$lang</code> (Idioma):</strong> Se usa en funciones que contienen texto en su salida (nombre del mes, la palabra "hace"). Si deja este parámetro vacío, el sistema opera <strong>por defecto en <code>'tr'</code> (Turco)</strong>. Si está haciendo un proyecto multilingüe, simplemente ingrese el código del idioma (<code>tr, en, de, fr, es</code>) en el segundo parámetro. (Ej: <code>timeAgo($fecha, 'es')</code> ➔ hace 5 minutos)</li>
+            </ul>
+        </div>
+        <pre><code><span class="cm">&lt;!-- Supongamos que es una marca de tiempo UNIX obtenida con la función time() --&gt;</span>
+<span class="kw">&lt;?php</span> <span class="var">$fecha</span> = <span class="fn">time</span>(); <span class="kw">?&gt;</span>
+<span class="cm">&lt;!-- Fecha completa según el idioma --&gt;</span>
+&lt;span&gt;&lt;?= <span class="fn">fulldateName</span>(<span class="var">$fecha</span>, <span class="st">'es'</span>) ?&gt;&lt;/span&gt;
+<span class="cm">&lt;!-- Salida: 24 de julio de 2026 --&gt;</span>
+<span class="cm">&lt;!-- Representación de tiempo estilo redes sociales --&gt;</span>
+&lt;span&gt;&lt;?= <span class="fn">timeAgo</span>(<span class="var">$fecha</span>, <span class="st">'en'</span>) ?&gt;&lt;/span&gt;
+<span class="cm">&lt;!-- Salida: 5 minutes ago --&gt;</span>
+&lt;span&gt;&lt;?= <span class="fn">timeAgo</span>(<span class="var">$fecha</span>, <span class="st">'de'</span>) ?&gt;&lt;/span&gt;
+<span class="cm">&lt;!-- Salida: vor 5 Minuten --&gt;</span></code></pre>
+    </section>
+    <section id="vh-format">
+        <h2>Ayudantes de Vista (View Helpers) — Formateo de Texto <span class="tag b-view">ViewMethod</span></h2>
+        <div class="card">
+            <h3><code>truncate($text, $length, $append)</code></h3>
+            <span class="ret">string truncate(string $text, int $length = 100, string $append = '...')</span>
+            <p>Recorta textos largos (por ejemplo, resúmenes de blog) en el límite de caracteres deseado sin cortar la última palabra y agrega el sufijo especificado al final.</p>
+            <pre><code>&lt;p&gt;&lt;?= <span class="fn">truncate</span>(<span class="var">$post</span>[<span class="st">'contenido'</span>], <span class="nu">160</span>, <span class="st">'...'</span>) ?&gt;&lt;/p&gt;</code></pre>
+        </div>
+    </section>
+    <section id="vh-money">
+        <h2>Ayudantes de Vista (View Helpers) — <code>money()</code> <span class="tag b-view">ViewMethod</span></h2>
+        <p>Formatea la cantidad con el símbolo de moneda. El código de la moneda (ISO) determina automáticamente la ubicación del símbolo. La moneda por defecto es <code class="ic">usd</code>.</p>
+        <span class="ret">string money(float $amount, string $currency = 'usd')</span>
+        <table class="sig-table">
+            <thead><tr><th>Código</th><th>Salida</th><th>Moneda</th></tr></thead>
+            <tbody>
+                <tr><td>usd</td><td>$1.250,00</td><td>Dólar estadounidense</td></tr>
+                <tr><td>eur</td><td>1.250,00 €</td><td>Euro</td></tr>
+                <tr><td>try / tl</td><td>1.250,00 ₺</td><td>Lira Turca</td></tr>
+                <tr><td>gbp</td><td>£1.250,00</td><td>Libra Esterlina Británica</td></tr>
+                <tr><td>jpy</td><td>1.250,00 ¥</td><td>Yen Japonés</td></tr>
+                <tr><td>inr</td><td>1.250,00 ₹</td><td>Rupia India</td></tr>
+                <tr><td>rub</td><td>1.250,00 ₽</td><td>Rublo Ruso</td></tr>
+                <tr><td>krw</td><td>1.250,00 ₩</td><td>Won Surcoreano</td></tr>
+                <tr><td>brl</td><td>R$1.250,00</td><td>Real Brasileño</td></tr>
+                <tr><td>aed</td><td>1.250,00 د.إ</td><td>Dírham de EAU</td></tr>
+            </tbody>
+        </table>
+        <pre><code>&lt;span&gt;&lt;?= <span class="fn">money</span>(<span class="var">$producto</span>[<span class="st">'precio'</span>], <span class="st">'try'</span>) ?&gt;&lt;/span&gt;
+<span class="cm">&lt;!-- Salida: 1.250,00 ₺ --&gt;</span>
+&lt;span&gt;&lt;?= <span class="fn">money</span>(<span class="var">$producto</span>[<span class="st">'precio'</span>], <span class="st">'usd'</span>) ?&gt;&lt;/span&gt;
+<span class="cm">&lt;!-- Salida: $1.250,00 --&gt;</span></code></pre>
+    </section>
+    <!-- ====== SYSTEM HELPERS ====== -->
+    <section id="sh-json">
+        <h2>Ayudantes del Sistema (System Helpers) — <code>jsonResponse()</code> <span class="tag b-api">SystemMethod</span></h2>
+        <p>Configura el encabezado JSON, proporciona el código de estado HTTP y emite la salida de manera segura con json_encode, luego termina el script. <strong>Todas las respuestas de API deben darse a través de esta función.</strong></p>
+        <span class="ret">void jsonResponse(array $data, int $statusCode = 200)</span>
+        <pre><code><span class="cm">// Respuesta exitosa</span>
+<span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'success'</span>, <span class="st">'data'</span> =&gt; <span class="var">$usuario</span>], <span class="nu">200</span>);
+<span class="cm">// Respuesta de error</span>
+<span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'error'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Acceso no autorizado.'</span>], <span class="nu">401</span>);</code></pre>
+    </section>
+    <section id="sh-csrf">
+        <h2>Ayudantes del Sistema (System Helpers) — <code>verifyCsrf()</code> <span class="tag b-api">SystemMethod</span></h2>
+        <p>Verifica que la solicitud POST entrante proviene de un formulario legítimo. Si no se agregó <code class="ic">csrfField()</code> dentro del formulario o si el token no es válido, devuelve false.</p>
+        <span class="ret">bool verifyCsrf(string $token)</span>
+        <pre><code><span class="kw">if</span> (!<span class="fn">verifyCsrf</span>(<span class="var">$_POST</span>[<span class="st">'csrf_token'</span>] ?? <span class="st">''</span>)) {
+    <span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'error'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Token CSRF no válido.'</span>], <span class="nu">403</span>);
+}</code></pre>
+    </section>
+    <section id="sh-sanitize">
+        <h2>Ayudantes del Sistema (System Helpers) — Funciones de Sanitización <span class="tag b-api">SystemMethod</span></h2>
+        <table class="sig-table">
+            <thead><tr><th>Función</th><th>Descripción</th></tr></thead>
+            <tbody>
+                <tr><td>sanitizeInt($value)</td><td>Elimina todas las letras, símbolos y comas que contiene, dejando <strong>solo números enteros</strong>. Utilizado para ID o límites.</td></tr>
+                <tr><td>sanitizeFloat($value)</td><td>Limpia todo excepto números decimales (fraccionarios). Utilizado para montos de dinero o métricas.</td></tr>
+                <tr><td>sanitizeString($value)</td><td>Destruye todas las <strong>etiquetas HTML y PHP (<code>&lt;script&gt;</code>, <code>&lt;iframe&gt;</code>, etc.)</strong> para evitar ataques XSS y derivados. Deja un texto sin formato y seguro.</td></tr>
+                <tr><td>sanitizeEmail($email)</td><td>Filtra todos los caracteres inválidos y peligrosos que no se ajustan al formato de correo electrónico.</td></tr>
+            </tbody>
+        </table>
+        <pre><code><span class="var">$id</span>    = <span class="fn">sanitizeInt</span>(<span class="var">$_POST</span>[<span class="st">'id'</span>] ?? <span class="nu">0</span>);
+<span class="var">$nombre</span>= <span class="fn">sanitizeString</span>(<span class="var">$_POST</span>[<span class="st">'nombre'</span>] ?? <span class="st">''</span>);
+<span class="var">$email</span> = <span class="fn">sanitizeEmail</span>(<span class="var">$_POST</span>[<span class="st">'email'</span>] ?? <span class="st">''</span>);</code></pre>
+    </section>
+    <section id="sh-request">
+        <h2>Ayudantes del Sistema (System Helpers) — HTTP y Petición <span class="tag b-api">SystemMethod</span></h2>
+        <table class="sig-table">
+            <thead><tr><th>Función</th><th>Descripción</th></tr></thead>
+            <tbody>
+                <tr><td>isAjax()</td><td>Comprueba el encabezado <code>HTTP_X_REQUESTED_WITH</code> para verificar si la solicitud vino de Fetch API / XMLHttpRequest.</td></tr>
+                <tr><td>getClientIp()</td><td>Captura de forma segura la dirección IP real del usuario (incluso si está detrás de proxies o Cloudflare).</td></tr>
+                <tr><td>redirect($url)</td><td>Crea un encabezado de Location y finaliza de inmediato la ejecución.</td></tr>
+            </tbody>
+        </table>
+        <pre><code><span class="cm">// Bloquear acceso directo desde el navegador al endpoint API</span>
+<span class="kw">if</span> (!<span class="fn">isAjax</span>()) {
+    <span class="fn">jsonResponse</span>([<span class="st">'error'</span> =&gt; <span class="st">'El acceso directo está restringido.'</span>], <span class="nu">403</span>);
+}
+<span class="cm">// Redirigir si no hay sesión</span>
+<span class="kw">if</span> (!isset(<span class="var">$_SESSION</span>[<span class="st">'user'</span>])) {
+    <span class="fn">redirect</span>(<span class="st">'/login.php'</span>);
+}
+<span class="var">$ip</span> = <span class="fn">getClientIp</span>(); <span class="cm">// IP real incluso detrás de Cloudflare</span></code></pre>
+    </section>
+    <section id="sh-security">
+        <h2>Ayudantes del Sistema (System Helpers) — Seguridad <span class="tag b-sec">SystemMethod</span></h2>
+        <table class="sig-table">
+            <thead><tr><th>Función</th><th>Descripción</th></tr></thead>
+            <tbody>
+                <tr><td>generateCsrf()</td><td>Genera un nuevo token CSRF y lo guarda en la sesión</td></tr>
+                <tr><td>generateToken($length)</td><td>Cadena hex aleatoria segura criptográficamente (restablecimiento de contraseña, clave API, etc.)</td></tr>
+                <tr><td>hashPassword($password)</td><td>Hashea la contraseña con bcrypt</td></tr>
+                <tr><td>verifyPassword($password, $hash)</td><td>Verifica la contraseña con el hash</td></tr>
+            </tbody>
+        </table>
+        <pre><code><span class="cm">// Generación de token seguro (clave API, enlace de verificación de correo electrónico, etc.)</span>
+<span class="var">$token</span> = <span class="fn">generateToken</span>(<span class="nu">32</span>);
+<span class="cm">// ⚠️ Nota: Se generan 32 bytes de datos, pero debido a que se convierte al formato</span>
+<span class="cm">// hexadecimal (base 16), la salida es exactamente el doble, es decir, una cadena de 64 caracteres de largo.</span>
+<span class="cm">// Registro de contraseña</span>
+<span class="var">$hash</span> = <span class="fn">hashPassword</span>(<span class="var">$_POST</span>[<span class="st">'clave'</span>]);
+<span class="cm">// Verificación de contraseña</span>
+<span class="kw">if</span> (!<span class="fn">verifyPassword</span>(<span class="var">$_POST</span>[<span class="st">'clave'</span>], <span class="var">$usuario</span>[<span class="st">'clave_hash'</span>])) {
+    <span class="fn">jsonResponse</span>([<span class="st">'error'</span> =&gt; <span class="st">'Contraseña incorrecta.'</span>], <span class="nu">401</span>);
+}</code></pre>
+    </section>
+    <!-- ====== API GÜVENLİĞİ ====== -->
+    <section id="api-methods">
+        <h2>API — Control de Métodos HTTP <span class="tag b-sec">ApiControl</span></h2>
+        <p>El arreglo <code class="ic">$allowedMethods</code> debe definirse <strong>antes</strong> del require de ApiControl. Al leer este arreglo, ApiControl rechaza automáticamente las solicitudes de los métodos no permitidos con un <code class="ic">405 Method Not Allowed</code>.</p>
+        <pre><code><span class="cm">// Un endpoint que solo acepta GET y POST</span>
+<span class="var">$allowedMethods</span> = [<span class="st">'GET'</span>, <span class="st">'POST'</span>];
+<span class="fn">require_once</span> ... . <span class="st">'/../app/ApiControl.php'</span>;
+<span class="cm">// Un endpoint que solo acepta DELETE</span>
+<span class="var">$allowedMethods</span> = [<span class="st">'DELETE'</span>];
+<span class="fn">require_once</span> ... . <span class="st">'/../app/ApiControl.php'</span>;</code></pre>
+        <p>Las solicitudes de preflight <code class="ic">OPTIONS</code> devuelven automáticamente <code class="ic">200</code> para CORS y el script termina — no es necesaria ninguna intervención manual.</p>
+    </section>
+    <section id="api-cors">
+        <h2>API — CORS <span class="tag b-api">ApiControl (Comentado)</span></h2>
+        <p>Si desea permitir el acceso a la API desde otros dominios o aplicaciones móviles, active el bloque CORS en <code class="ic">ApiControl.php</code>.</p>
+        <pre><code><span class="cm">// Dentro de ApiControl.php — se activa eliminando el comentario</span>
+header(<span class="st">"Access-Control-Allow-Origin: https://su-dominio.com"</span>);
+header(<span class="st">"Access-Control-Allow-Methods: GET, POST, OPTIONS"</span>);
+header(<span class="st">"Access-Control-Allow-Headers: Content-Type, Authorization"</span>);</code></pre>
+        <div class="alert a-warn">
+            <strong>⚠️</strong> No utilice <code class="ic">*</code> (todos los dominios) en un entorno de Producción. Especifique explícitamente la dirección del dominio.
+        </div>
+    </section>
+    <section id="api-rate">
+        <h2>API — Limitación de Tasa (Rate Limiting) <span class="tag b-api">ApiControl (Comentado)</span></h2>
+        <p>Para evitar que usuarios malintencionados o bots inunden (flood) la API, puede activar el bloque de Rate Limiting dentro de <code class="ic">ApiControl.php</code>. La regla por defecto es: <strong>60 peticiones en 60 segundos por IP</strong>.</p>
+        <div class="alert a-warn" style="margin-top: 10px; margin-bottom: 20px;">
+            <strong>⚠️ Servidor Redis Requerido:</strong> La función de Limitación de Tasa (Rate Limiting) opera usando Redis a través de la clase <code>\Src\Service\RedisService::getInstance()</code>. Antes de descomentar este bloque de código, asegúrese de haber instalado un servicio Redis en su proyecto y haber creado una clase de conexión bajo <code>src/Service/</code>.
+        </div>
+        <pre><code><span class="cm">// Si hay más de 60 peticiones en 60 segundos de la misma IP:</span>
+http_response_code(<span class="nu">429</span>); <span class="cm">// Demasiadas Peticiones</span>
+echo json_encode([<span class="st">'error'</span> =&gt; <span class="st">'Demasiadas peticiones. Por favor, espere.'</span>]);</code></pre>
+    </section>
+    <!-- ====== WORKFLOW ====== -->
+    <section id="workflow">
+        <h2>Flujo de Trabajo Completo: Formulario de Contacto (De Extremo a Extremo)</h2>
+        <p>Examinemos paso a paso cómo desarrollar una función de <strong>Formulario de Contacto</strong> con los estándares de ArtiFrame de principio a fin.</p>
+        <ol class="steps">
+            <li>
+                <div>
+                    <strong>Cree el Archivo de Vista (View)</strong>
+                    <pre><code>artiframe&gt; <span class="fn">make:view</span> <span class="st">contacto.php</span>
+<span class="cm">✔  public/contacto.php</span>
+<span class="cm">✔  public/assets/css/contacto.css</span>
+<span class="cm">✔  public/assets/js/contacto.js</span></code></pre>
+                </div>
+            </li>
+            <li>
+                <div>
+                    <strong>Cree un Endpoint API</strong>
+                    <pre><code>artiframe&gt; <span class="fn">make:api</span> <span class="st">standart</span> <span class="st">api/contacto/enviar.php</span></code></pre>
+                </div>
+            </li>
+            <li>
+                <div>
+                    <strong>Codifique el Formulario HTML</strong><br>
+                    Añada el siguiente formulario al archivo <code class="ic">public/contacto.php</code>:
+                    <pre><code>&lt;form action="/api/contacto/enviar.php" method="POST"&gt;
+    &lt;?= <span class="fn">csrfField</span>() ?&gt;
+    &lt;input type="text"  name="nombre"    placeholder="Su Nombre"&gt;
+    &lt;input type="email" name="email"     placeholder="Correo Electrónico"&gt;
+    &lt;textarea name="mensaje" placeholder="Su Mensaje"&gt;&lt;/textarea&gt;
+    &lt;button type="submit" data-js="<span class="st">contacto-enviar</span>"&gt;Enviar&lt;/button&gt;
+&lt;/form&gt;</code></pre>
+                </div>
+            </li>
+            <li>
+                <div>
+                    <strong>Conecte la API de Fetch con JavaScript</strong><br>
+                    En el archivo <code class="ic">public/assets/js/contacto.js</code>:
+                    <pre><code>document.<span class="fn">querySelector</span>(<span class="st">'[data-js="contacto-enviar"]'</span>).<span class="fn">addEventListener</span>(<span class="st">'click'</span>, async (e) =&gt; {
+    e.<span class="fn">preventDefault</span>();
+    <span class="kw">const</span> formData = <span class="kw">new</span> <span class="fn">FormData</span>(e.target.<span class="fn">closest</span>(<span class="st">'form'</span>));
+    <span class="kw">const</span> res = <span class="kw">await</span> <span class="fn">fetch</span>(<span class="st">'/api/contacto/enviar.php'</span>, {
+        method: <span class="st">'POST'</span>,
+        body: formData
+    });
+    <span class="kw">const</span> data = <span class="kw">await</span> res.<span class="fn">json</span>();
+    <span class="fn">console</span>.<span class="fn">log</span>(data);
+});</code></pre>
+                </div>
+            </li>
+            <li>
+                <div>
+                    <strong>Complete la Lógica del Servidor (Backend)</strong><br>
+                    En el archivo <code class="ic">public/api/contacto/enviar.php</code>:
+                    <pre><code><span class="kw">&lt;?php</span>
+<span class="var">$allowedMethods</span> = [<span class="st">'POST'</span>];
+<span class="fn">require_once</span> <span class="var">$_SERVER</span>[<span class="st">'DOCUMENT_ROOT'</span>] . <span class="st">'/../app/ApiControl.php'</span>;
+<span class="kw">use</span> Bin\SystemMethod;
+<span class="cm">// 1. Validación CSRF</span>
+<span class="kw">if</span> (!<span class="fn">verifyCsrf</span>(<span class="var">$_POST</span>[<span class="st">'csrf_token'</span>] ?? <span class="st">''</span>)) {
+    <span class="fn">jsonResponse</span>([<span class="st">'error'</span> =&gt; <span class="st">'Token inválido.'</span>], <span class="nu">403</span>);
+}
+<span class="cm">// 2. Sanitización de Datos</span>
+<span class="var">$nombre</span>  = <span class="fn">sanitizeString</span>(<span class="var">$_POST</span>[<span class="st">'nombre'</span>] ?? <span class="st">''</span>);
+<span class="var">$email</span>   = <span class="fn">sanitizeEmail</span>(<span class="var">$_POST</span>[<span class="st">'email'</span>] ?? <span class="st">''</span>);
+<span class="var">$mensaje</span> = <span class="fn">sanitizeString</span>(<span class="var">$_POST</span>[<span class="st">'mensaje'</span>] ?? <span class="st">''</span>);
+<span class="cm">// 3. Lógica de Negocio (Enviar correo, guardar en DB, etc.)</span>
+<span class="cm">// ...</span>
+<span class="cm">// 4. Respuesta</span>
+<span class="fn">jsonResponse</span>([<span class="st">'status'</span> =&gt; <span class="st">'success'</span>, <span class="st">'message'</span> =&gt; <span class="st">'Su mensaje ha sido recibido.'</span>], <span class="nu">200</span>);</code></pre>
+                </div>
+            </li>
+        </ol>
+        <div class="alert a-success">
+            <strong>✅ ¡Completado!</strong> Ha creado un flujo de formulario totalmente seguro y que cumple con los estándares, con protección XSS, validación CSRF, restricción de métodos HTTP y arquitectura data-js.
+        </div>
+    </section>
+</main>
+<script>
+    const sections = document.querySelectorAll('section[id], header[id]');
+    const links = document.querySelectorAll('.sidebar nav a');
+    const observer = new IntersectionObserver((entries) => {
+        entries.forEach(entry => {
+            if (entry.isIntersecting) {
+                links.forEach(l => l.classList.remove('active'));
+                const active = document.querySelector(`.sidebar nav a[href="#${entry.target.id}"]`);
+                if (active) active.classList.add('active');
+            }
+        });
+    }, { rootMargin: '-20% 0px -70% 0px' });
+    sections.forEach(s => observer.observe(s));
+</script>
+</body>
+</html>