@mozole/cli 1.4.3 → 2.0.0-b

package/LICENSE

@@ -1,9 +1,21 @@
 MIT License
 
-Copyright (c) 2026 Mozole contributors
+Copyright (c) 2026 Mozole Studio
 
-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:
+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 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.
+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

@@ -1,137 +1,110 @@
-# Mozole CLI
-
-Mozole scaffolds React + Vite projects using React Router Framework Mode. It prerenders static HTML and optionally adds a native PHP API. Node.js 22+, npm, and Windows or Linux are supported. PHP projects require PHP 8.0+.
-
-```sh
-npm install --global @mozole/cli
-mozole new my-site
-mozole new my-app --backend
-```
-
-Creation installs pinned dependencies and Chromium, formats the project, and moves the completed staging directory into place. Failed setup preserves available subprocess logs in a sibling `.mozole-<name>-failure-*` directory before removing staging. Existing target directories are preserved.
-
-## Default project
-
-The default project has **no CCE, token governor, telemetry, verification cache, MCP registration, or optimization hooks**. It does not depend on `@mozole/cli`, including transitively through its generated package lock. Verification and browser QA run through standalone project scripts. `MOZOLE_INSTALL_CCE` does not enable integrations.
-
-Basic `AGENTS.md` describes actual commands, source layout, and verification policy. `CLAUDE.md` imports it using `@AGENTS.md`. Neither file imposes CCE retrieval or token policies. No `.agents/`, `.codex/hooks.json`, or `.claude/settings.json` is generated by default.
-
-```sh
-cd my-site
-npm run dev
+# Mozole CLI (`@mozole/cli`)
+
+> **Mozole Studio** internal project generator and development cockpit tailored for autonomous agentic engineering workflows.
+
+---
+
+## Highlights
+
+- **Vite-Powered Frontend Engines:**
+  - **Standard Profile:** React 19 + React Router 7 (Framework Mode Plugin) + Static Pre-rendering (SSG) + Tailwind CSS v4 + bespoke Radix UI primitives.
+  - **Flagship Creative Profile (`--flagship`):** React 19 + Wouter + Lenis (Smooth Scroll) + Motion + Persistent 60fps Canvas/WebGL layer.
+- **Pure PHP 8.1+ Zero-Dependency Backend:**
+  - Engineered for budget shared hosting (cPanel 250k Inodes, 25 MB/s I/O, Imunify360).
+  - 5-Layer Security Architecture: Origin/Referer verification, honeypot spam protection, file-based IP rate-limiting, direct file access denial for `config.php`, input sanitization.
+- **10-Step Phased Development Pipeline:**
+  - Sequential phases (Phase 00–10) with status tracking in `docs/phases/status.md` and automated phase advancement commits (`mozole phase next`).
+  - Post-launch maintenance workflow (`mozole phase reopen <id>`).
+- **Architectural Fihrist (`docs/repomap/`):**
+  - Continuous mapping of architecture, bespoke UI primitives, application routes, and design tokens.
+- **Mozole Quality Kit:**
+  - Static PostCSS AST contract auditor enforcing token integrity (`src/styles/tokens.css`), banning literal colors, raw font families, and `transition: all`.
+  - Headless in-browser DOM geometry probe detecting layout reflow defects, text clipping, and minimum touch target violations.
+  - Automated WCAG 2.1 AA landmark and accessibility auditor.
+- **Interactive Terminal Cockpit (`mozole ui`):**
+  - Clean, lightweight TUI to inspect client projects, advance phases, and run deterministic verification.
+
+---
+
+## Installation & Local Development
+
+```bash
+# Clone and install dependencies
+git clone git@github.com:mozolestudio/cli.git
+cd MozoleCli
+npm install
+
+# Run verification suite (Biome lint, TypeScript typecheck, Vitest, build)
 npm run verify
-npm run qa
-npm run qa:interactive
-npm run qa:visual
-```
-
-`verify` runs lint, strict TypeScript, tests, and production build every time. PHP projects also run PHP version and recursive syntax checks first. `qa` starts a loopback development server on an available port, checks the configured routes at three viewports, and closes its browser and server. Normal QA never captures screenshots. `qa:visual` explicitly captures screenshots under `.mozole/qa/`. Optional `--diff` comparisons preserve the accepted baseline and fail when the configured threshold is exceeded. Reinstall Chromium with `npx playwright install chromium` if necessary.
-
-React Router uses `ssr: false` and `prerender: true`. The starter builds real HTML for `/`, `/about`, and `/contact` into `build/client/`, plus `__spa-fallback.html`. Production requires no Node server. See [React Router prerendering](https://reactrouter.com/how-to/pre-rendering).
-
-## Shared template workspaces
-
-Use a template workspace when multiple generated projects should share one pinned Node.js toolkit instead of installing a separate `node_modules` tree for every project:
 
-```sh
-mozole template init MozoleProjects
-cd MozoleProjects
-mozole new marketing-site
-mozole new admin-panel --backend
-mozole template adopt ../existing-vite-app
-mozole template list
-mozole ui
+# Run local development binary
+npm run dev -- --help
 ```
 
-The template root is an npm workspace marked by `.mozole/template.json`. Its `package.json` owns React, React Router, Vite, Tailwind, TypeScript, Biome, Vitest, Playwright, and the Mozole CLI. Child manifests retain standardized dependency declarations for framework compatibility, while npm hoists their physical installation to the root; no project-local `node_modules` is created. `mozole new` searches parent directories for the marker, so it automatically registers projects created from the template root or nested category folders such as `Architecture/`. Creation from inside an existing managed project is rejected to prevent accidental project nesting. Projects outside a template workspace retain the normal standalone installation behavior.
+---
 
-`mozole template adopt <path>` imports an external React/Vite project as a copy, leaving its source directory untouched. Running it for an existing direct child standardizes that project in place. Runtime, optional, peer, and development packages are merged into the root toolkit; template versions win conflicts so every managed project resolves one standardized version. The child's previous lockfile is archived under `.mozole/backups/`, and its disposable local `node_modules` is removed after a successful shared install. `--cce-install` remains available for optimized adoption.
+## Command Reference
 
-The TUI's **Servers** screen discovers nested Mozole projects and starts each configured npm development server on its preferred port or the next available port. Use Enter/`s` to toggle one server, `a` to start all, and `x` to stop all. Server output is retained under `.mozole/logs/servers/`. Managed servers are stopped when the TUI exits, so the UI remains the single lifecycle owner; disposable project-local Vite caches are cleaned on stop.
+### `mozole new <name> [--flagship] [--backend=php|node]`
+Generates a client project with Mozole Studio governance and canonical design tokens. Install its dependencies with `npm install`, then run `mozole verify` to check the generated project in your environment.
 
-## Design references and assets
+```bash
+# Standard React Router 7 + SSG + Tailwind v4 project
+mozole new acme-corp
 
-Place exported `design.md`, images, icons, fonts and reference screens under `docs/design/`. Generated `AGENTS.md` treats these as design evidence, preserves their intent, and requires checks for spacing, loaded fonts, foreground/background contrast, responsive behavior and interaction states. It permits justified corrections instead of blindly copying tokens. `docs/design/README.md` explains the handoff; no provider-specific design is generated. Existing exports remain untouched during adoption. Routine QA stays screenshot-free; visual comparison remains opt-in.
-
-## PHP backend
-
-```sh
-mozole new my-app --backend
-cd my-app
-npm run dev
-# In a separate terminal:
-npm run dev:api
-```
-
-Vite proxies `/api/` calls to PHP on `127.0.0.1:8000`. The PHP front controller serves `GET` and `HEAD` for `/api/health` and `/api/info`. Unknown endpoints return JSON 404; unsupported methods on known endpoints return JSON 405 with `Allow: GET, HEAD`.
-
-```sh
-npm run check:php
-npm run build:deploy
+# Flagship creative project with smooth scroll & persistent canvas
+mozole new studio-flagship --flagship
 ```
 
-`check:php` checks PHP 8.0+ and runs `php -l` on every PHP source file under `api/`. `build:deploy` validates PHP, builds the frontend, and assembles `deploy/` with static output, `api/`, and `.htaccess`. Existing deployment output is replaced with rollback on failed replacement. Upload the **contents** of `deploy/`, including hidden `.htaccess`, to an Apache/LiteSpeed document root with PHP and rewrite support. The supplied configuration assumes domain-root hosting. Nginx needs explicit PHP-FPM configuration; see generated `docs/backend-php.md`.
-
-Environment values come from the process environment using `getenv`; there is no implicit `.env` loader. Production and debug-off are the defaults. Database support is an optional PDO helper; configure `DB_DSN`, `DB_USER`, and `DB_PASS` through your host.
+### `mozole prototype init`
+Initializes a new prototype repository workspace with a multi-project `projects/` directory and shared token bridges.
 
-## Explicit integrations
+### `mozole adopt [path]`
+Adopts an existing web project into Mozole Studio governance, injecting `AGENTS.md`, `CLAUDE.md`, `docs/phases/status.md`, `docs/repomap/`, and design token foundations.
 
-```sh
-mozole cce install
-mozole new agent-site --cce-install
-# --install-cce is an alias; --backend can be combined with either flag.
-mozole adopt existing-site --cce-install
-```
-
-Only explicit `--cce-install`/`--install-cce` enables the CCE runtime integration, Codex/Claude hooks, Antigravity workspace files, token governor, telemetry, and verification/QA evidence reuse. The project then depends on the matching CLI version. `--scaffold` on `new` overrides integration flags.
+### `mozole phase [status|next|reopen]`
+Manages project progression through the 10-step atomic development lifecycle:
 
-CCE initialization uses the pinned release in `src/version.ts`. `mozole cce install` installs its runtime; creation reports when an unavailable runtime needs attention. Adoption with integration flags requires a runnable CCE runtime before installing managed integrations. Existing user instructions and unrelated hook/MCP entries are preserved. Managed instruction blocks and hook definitions are refreshed idempotently.
+- `mozole phase status` — Displays visual checklist and status for all phases.
+- `mozole phase next` — Advances one phase and creates a conventional commit (`feat(phase-XX): ...`) when Git is initialized. Complete the checklist and run `mozole verify` first; checklist completion is a developer responsibility. Failed commits restore the previous phase file and Git index.
+- `mozole phase reopen <id>` — Reopens a completed phase for post-launch maintenance.
 
-Optimized `AGENTS.md` provides the shared CCE-first contract; `CLAUDE.md` imports it and Antigravity rules reference it. Instructions are guidance, not execution proof. Codex discovers `AGENTS.md` by directory scope, with `AGENTS.override.md` taking precedence. Project hooks need host review/trust before execution. See [AGENTS.md discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md) and [Codex hooks](https://learn.chatgpt.com/docs/hooks).
+### `mozole repomap [sync|check]`
+Synchronizes and audits the `docs/repomap/` architectural index, component registry, and route catalog.
 
-Read and command policies run on `PreToolUse`. CCE retrieval tracking runs on `PostToolUse`, including MCP tool names, and ignores explicit tool-error responses. The Antigravity visual workflow provides a reason accepted by the visual QA gate. Host-specific agent sessions are not automatically launched by the CLI test suite.
+### `mozole test [contract|a11y|probe|all]`
+Executes Mozole Quality Kit verification suites:
+- `mozole test contract` — PostCSS AST design token contract audit (prohibits literal colors, `transition: all`, fixed viewport dimensions).
+- `mozole test a11y` — Static HTML and accessibility landmark hierarchy validation.
+- `mozole test probe` — Headless live DOM geometry and trace runner. Discovers local Brave/Chromium (or auto-provisions Playwright Chromium if absent). Measures live bounding boxes, horizontal overflow on mobile viewports (320px+), text clipping, touch targets (<24px), prefers-reduced-motion violations, and 200% text-zoom reflow stress. Strictly zero raster screenshots (`screenshots: false, snapshots: true`); emits full interactive trace packages to `docs/qa/trace.zip` for inspection via [trace.playwright.dev](https://trace.playwright.dev).
+- `mozole test all` (default) — Executes static contract and accessibility audits.
 
-Optimized verification/QA reuses matching successful evidence. Verification evidence covers all non-generated project files and is invalidated by CLI upgrades. Use `--force` for a fresh run. Routine QA is screenshot-free; visual QA uses explicit `--visual` and, after successful routine QA, `--reason` or `--force`. Enabled governors enforce read/command policies and can deny calls; they are not advisory-only. Local telemetry reports measured output compression and tool activity, not model billing savings.
+### `mozole verify [--probe]`
+The authoritative, multi-stage deterministic gate required before completing agentic tasks:
+1. AI Trace Scanner (strictly prohibits synthetic watermarks and bot co-author trailers)
+2. Biome lint & code style check
+3. Project `typecheck` script (including React Router type generation), or local TypeScript compiler
+4. Production build (`npm run build`)
+5. PostCSS design token contract audit
+6. Accessibility & landmark hierarchy validation against built HTML
+7. *(Optional with `--probe`)* Live headless DOM geometry & trace probe across critical viewports
 
-## Adopt an existing project
+Biome and TypeScript must be installed locally; verification never downloads missing CLI tools with `npx`. Standard projects emit static pages for `/`, `/about`, and `/contact` without requiring a Node server in production. See the [React Router pre-rendering documentation](https://reactrouter.com/how-to/pre-rendering) for hosting configuration.
 
-New projects include pinned Tailwind CSS v4 and `@tailwindcss/vite` by default in all modes, including PHP projects. `app/styles/global.css` imports Tailwind and keeps starter styles in the base layer. Adoption preserves existing CSS and Vite configuration; it does not automatically migrate older styling pipelines or inject Preflight into an existing design.
+The PHP contact backend requires an allowed Origin or a Referer with the same scheme, host and port as an allowed origin. Requests without either are rejected. Rate-limit storage errors return HTTP 503; mail transport failures return HTTP 502 with `success: false`. Configure `api/config.php` and the hosting mail transport before accepting real submissions.
 
-```sh
-mozole adopt ../existing-app
-```
+### `mozole doctor`
+Diagnoses workstation prerequisites: Node.js (>= 20), Git, PHP 8.1+ status, local Chromium/Brave browser engine availability, and network port availability.
 
-Adoption reconciles a React/Vite or React Router project with the current project system. Without `--cce-install`, it removes Mozole-owned CCE integrations, optimization hooks and state, including from previously optimized projects, and installs standalone verification/QA. The flag explicitly selects the optimized system. User instructions, unrelated integrations, application source and design exports are preserved. Recognized unchanged legacy PHP templates are upgraded; customized backend files are retained with a review notice. Replaced files and obsolete state are archived under `.mozole/backups/adopt-*`; managed files are restored if installation fails. Tooling versions and npm dependencies are reconciled on every adoption. Custom verifier commands and configured QA servers remain in use. Repeating adoption does not duplicate managed instruction blocks.
-
-## CLI commands
-
-```text
-mozole new <name> [--backend] [--cce-install] [--verbose]
-mozole template init [folder]
-mozole template adopt <project-path> [--cce-install] [--verbose]
-mozole template list
-mozole adopt <path> [--cce-install] [--verbose]
-mozole doctor
-mozole verify [--force]
-mozole qa [--interactive | --visual [--diff]] [--force]
-mozole logs [name] [--raw]
-mozole cce install
-mozole stats
-mozole ui
-```
+### `mozole ui` (or bare `mozole`)
+Launches the interactive terminal cockpit.
 
-`doctor` checks runtime, project tooling, and optional PHP syntax. CCE probes are omitted for plain projects. `mozole verify` and `mozole qa` can also operate on plain project metadata without reading or writing optimization state. `stats` reports that statistics are disabled in plain projects. Standalone project QA supports normal, interactive, and visual modes; pixel diffing remains in the optional CLI QA runner.
+---
 
-## Development
+## Repository Governance
 
-```sh
-npm ci
-npx playwright install chromium
-npm run verify
-npm run test:smoke
-npm pack --dry-run
-```
+This project is governed by [AGENTS.md](./AGENTS.md). All automated agents and contributors must adhere to the rules therein.
 
-The CI matrix runs on native Windows and Ubuntu with PHP. It covers real PHP routing, method handling, syntax failures, deployment replacement and rollback, default scaffold isolation, agent-file wiring, conservative adoption, and generated frontend/PHP/optimized projects. The optimized smoke scenario skips CCE initialization; live CCE installation is covered separately with runtime fixtures.
+## License
 
-Subprocesses use argument arrays and `shell: false`. Persisted configuration, state, and telemetry use temporary files and atomic replacement. Dependency versions are pinned centrally in `src/version.ts`.
+MIT © Mozole Studio

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-export declare function isCliEntrypoint(entryUrl: string, invokedPath: string | undefined): boolean;
-export declare function main(args?: string[], cwd?: string): Promise<number>;
+export declare const main: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAsBA,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,OAAO,CAOT;AAuDD,wBAAsB,IAAI,CACxB,IAAI,WAAwB,EAC5B,GAAG,SAAgB,GAClB,OAAO,CAAC,MAAM,CAAC,CA2KjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+LA,eAAO,MAAM,IAAI,qDAuBf,CAAC;AAEH,wBAAgB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAElE"}