@deneb-ui/cli 2.0.0

package/README.md

@@ -0,0 +1,197 @@
+# @fivora/cli
+
+Official developer CLI for creating, initializing, testing, validating, and packaging **Fivora** templates.
+
+[![npm version](https://img.shields.io/npm/v/@fivora/cli.svg)](https://www.npmjs.com/package/@fivora/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-teal.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Installation
+
+You can run commands directly using `npx`:
+```bash
+npx @fivora/cli <command>
+```
+
+Or install globally:
+```bash
+npm install -g @fivora/cli
+```
+
+Or install as a project devDependency:
+```bash
+npm install -D @fivora/cli
+```
+
+The CLI command is available as `fivora`.
+
+---
+
+## Commands
+
+### 1. `fivora init` (Configure an Existing Project)
+Converts any **existing Next.js project** into a compliant Fivora template:
+
+```bash
+# Inside your existing Next.js project directory:
+npx @fivora/cli init
+# or if installed globally / locally:
+fivora init
+```
+
+**What it does automatically:**
+- Scans `src/app`, `app`, and `pages` to discover your existing routes (e.g. `/products`, `/about`, `/contact`).
+- Generates `fivora-template.json` (Version 2 strict visual editing contract) with detected pages.
+- Generates `src/data/site-data.json` for merchant branding, navigation labels, and editable copy.
+- Injects npm scripts (`lab`, `validate`, `zip`, `package:template`) into `package.json`.
+- Installs `@fivora/editable-components` and `@fivora/cli`.
+- Checks `next.config` to verify `output: 'export'` for static export builds.
+
+**Options:**
+- `--skip-install` – Skip automatic `npm install` of dependencies.
+
+---
+
+### 2. `fivora create <project-name>` (Start from Scratch)
+Scaffolds a brand-new, production-ready Fivora store with Next.js App Router, Tailwind/CSS, and editable components pre-configured:
+
+```bash
+fivora create my-store
+cd my-store
+npm run dev
+```
+
+---
+
+### 3. `fivora lab [path]` (Visual Editing Lab)
+Starts the local **Fivora Visual Editing Lab**. It boots your Next.js store inside an interactive editor simulation so you can test merchant visual click-to-edit interactions and field highlights before uploading.
+
+```bash
+fivora lab .
+# Or via npm script:
+npm run lab
+```
+
+**Options:**
+- `--api-port <port>` – Controller API port (default: `4174`)
+- `--preview-port <port>` – Template dev server port (default: `4173`)
+- `--skip-install` – Do not install missing dependencies automatically
+
+---
+
+### 4. `fivora validate [path]` (Contract Preflight Validation)
+Runs strict preflight compliance checks against the Fivora template contract:
+
+- **Manifest Validation:** Ensures `fivora-template.json` satisfies contract version 2.
+- **Probe Fixture Test:** Verifies that all `data-preview-field-path` annotations render without breaking.
+- **Empty-State Safety:** Verifies the template does not crash when merchant content is empty or omitted.
+- **Unselected Page Link Filtering:** Verifies links to optional unselected pages are cleanly filtered.
+
+```bash
+fivora validate .
+# Or via npm script:
+npm run validate
+```
+
+**Options:**
+- `--skip-install` – Skip dependency installation during check
+- `--skip-build` – Skip building output directory
+- `--json` – Output results as structured JSON
+
+---
+
+### 5. `fivora zip [path]` (Clean 1-Click Packaging)
+Packages your template into an upload-ready `.zip` file for the Fivora Developer Portal.
+
+```bash
+fivora zip .
+# Or via npm script:
+npm run zip
+```
+
+**Automatic Exclusions:**
+Strips out heavy and private files automatically:
+- `node_modules/`
+- `.next/` and `.turbo/`
+- `.git/`
+- `.env*` files
+- Temporary logs and build caches
+
+Output is saved as `fivora-template.zip` in your project root.
+
+---
+
+### 6. `fivora update [path]` (Update Fivora Dependencies)
+Updates `@fivora/editable-components` and `@fivora/cli` to their latest versions:
+
+```bash
+fivora update
+# Or via npm script:
+npm run update:fivora
+```
+
+**What it does:**
+- In standard/published projects: Runs `npm install @fivora/editable-components@latest @fivora/cli@latest`.
+- In local development workspaces: Automatically detects `file:` package paths (or with `--local` flag) and re-links directly against local package folders.
+
+**Options:**
+- `--local` / `-l` (optional `--local=<path>`) – Re-link against a local workspace for developing packages locally (defaults to `/mnt/GAMES/GitHub/fivora_package`).
+
+---
+
+## Template Manifest (`fivora-template.json`)
+
+The template manifest declares template metadata, pages, and editable schema:
+
+```json
+{
+  "framework": "nextjs-static-export",
+  "version": 2,
+  "visualEditing": {
+    "contractVersion": 1,
+    "mode": "strict",
+    "controlOnlyPaths": []
+  },
+  "siteDataFile": "src/data/site-data.json",
+  "outputDirectory": "out",
+  "installCommand": "npm install",
+  "buildCommand": "npm run build",
+  "basePathEnvVar": "NEXT_PUBLIC_SITE_BASE_PATH",
+  "pages": [
+    { "id": "home", "label": "Home", "route": "/", "required": true },
+    { "id": "products", "label": "Products", "route": "/products" },
+    { "id": "contact", "label": "Contact", "route": "/contact", "required": true }
+  ],
+  "editorSchema": {
+    "version": 1,
+    "sections": []
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### `Error: Template manifest is missing or invalid`
+Your project is missing `fivora-template.json`. Run:
+```bash
+npx @fivora/cli init
+```
+This will automatically generate the manifest and site data for your project.
+
+### `Error: Template manifest framework must be "nextjs-static-export"`
+Make sure your `next.config.ts` or `next.config.js` specifies static export:
+```typescript
+const nextConfig = {
+  output: 'export',
+};
+export default nextConfig;
+```
+
+---
+
+## License
+
+MIT © [Fivora](https://fivora.com)