ozmoz 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# ozmoZ
+
+### The Client-Side Data OS for Modern Web Apps & AI Vibe-Coding
+
+ozmoZ manages the complete application data lifecycle: from AI-assisted schema modeling (Alex AI DBA) to deterministic Edge enforcement and seamless client-side execution.
+
+Like an architect drafting blueprints before construction begins, Alex AI models your business domain and spins up an instant, production-ready backend. ozmoZ delivers relational integrity, strict typing, and Edge security to MongoDB Atlas without writing backend boilerplate.
+
+---
+
+<!-- STREAMING_CHUNK:Documenting core value propositions... -->
+
+## Why ozmoZ?
+
+- **100% Frontend Focus**: Zero servers, zero custom REST APIs, and zero SQL migrations. Build full-stack applications purely from the client.
+- **AI Agent Accelerator**: Eliminates hallucinations and cuts token usage by 90% via deterministic contracts (`svro.schema.json`, `svro.workflow.json`). Agents (Claude Code, Cursor, Windsurf) focus 100% of their reasoning on UX.
+- **Deterministic Edge Gatekeeper**: Sub-millisecond $O(1)$ schema validation at the cloud edge before writes hit the database.
+- **Zero-Crash Native Web Components**: 7 built-in, framework-agnostic Custom Elements (`<oz-*>`) preventing white-screen crashes on missing or partial data.
+- **Zero-Rewrite Philosophy**: Write the exact same frontend code in trial mode (`OZ_PROTOTYPE=true`) and production (`OZ_PROTOTYPE=false`).
+
+---
+
+<!-- STREAMING_CHUNK:Documenting installation and setup commands... -->
+
+## Quick Start
+
+### 1. New Project with an AI Agent
+
+Let your terminal AI agent build the project for you:
+
+```bash
+npx ozmoz start claude "Your application idea"
+```
+
+Or configure your environment and MCP server:
+
+```bash
+npx ozmoz login     # Authenticate once in your browser
+npx ozmoz mcp       # Generates AGENTS.md, CLAUDE.md, GEMINI.md and MCP settings
+```
+
+### 2. Integration into an Existing Frontend
+
+Install the package in your Vite project:
+
+```bash
+npm install ozmoz
+npx ozmoz init --keyApp=<APP_KEY> --token=<BOOTSTRAP_TOKEN>
+npx ozmoz sync
+```
+
+---
+
+<!-- STREAMING_CHUNK:Documenting execution modes and environment configuration... -->
+
+## Execution Modes (`.env`)
+
+Configure your operational mode in `.env`:
+
+```env
+# Trial / Sandbox mode: all operations are simulated locally with demo data (oz.seed).
+# Test code for authentication is always: 0000
+OZ_PROTOTYPE=true
+
+# Live mode: enforced physical schema, Edge security, and real database persistence.
+OZ_PROTOTYPE=false
+```
+
+---
+
+<!-- STREAMING_CHUNK:Documenting CRUD operations and strict governance rules... -->
+
+## SDK Usage & Strict Governance
+
+Every write operation requires literal governance metadata `{ desc, role, guard }` to ensure contract validation.
+
+### Writing Data
+
+```javascript
+// 1. Insert a document with mandatory governance
+const res = await oz.add('orders', {
+  product: 'Desk Pro',
+  price: 299
+}, {
+  desc: 'Create customer order',
+  role: 'AUTHENTICATED',
+  guard: 'price > 0'
+});
+
+if (!res.success) {
+  console.error('Order creation failed:', res.error);
+} else {
+  console.log('Created document ID:', res.documentId);
+}
+
+// 2. Update a document
+const updateRes = await oz.update('orders', doc._id, {
+  price: 249
+}, {
+  desc: 'Apply discount on order',
+  role: 'MANAGER'
+});
+
+// 3. Delete a document
+const delRes = await oz.delete('orders', doc._id, {
+  desc: 'Cancel and delete order',
+  role: 'ADMIN'
+});
+```
+
+<!-- STREAMING_CHUNK:Documenting read operations and authentication... -->
+
+### Reading Data
+
+```javascript
+// Read all global documents in a collection
+const orders = await oz.getDocsG('orders');
+
+// Read documents owned by the authenticated user
+const userOrders = await oz.getDocsU('orders');
+
+// Read a single document by its _id
+const order = await oz.getDoc('orders', 'order_123');
+```
+
+### Authentication (Passwordless OTP)
+
+```javascript
+// Step 1: Send OTP code (In trial mode, code is always 0000)
+const otpRes = await oz.sendotpsvro('user@example.com');
+
+// Step 2: Verify OTP code and establish session
+const authRes = await oz.verifyotpsvro('user@example.com', '0000');
+if (authRes.success) {
+  console.log('Logged in user:', authRes.user);
+}
+
+// Check session status
+const loggedIn = await oz.isAuthenticated();
+```
+
+---
+
+<!-- STREAMING_CHUNK:Documenting defensive UI web components... -->
+
+## Zero-Crash UI Components
+
+Render data safely without risk of runtime null-pointer exceptions:
+
+```html
+<!-- Text with fallback -->
+<oz-text value={item.name} fallback="No name" />
+
+<!-- Currency formatting with strict fallback -->
+<oz-number value={item.price} currency="EUR" invalid-fallback="0" />
+
+<!-- Boolean toggle representation -->
+<oz-toggle value={item.isActive} label-true="Active" label-false="Inactive" />
+
+<!-- Formatted date display -->
+<oz-date value={item.createdAt} locale="en-US" invalid-fallback="Invalid date" />
+
+<!-- Enum status validator -->
+<oz-enum value={item.status} allowed="PENDING,CONFIRMED,DELIVERED" invalid-fallback="Unknown status" />
+
+<!-- Relational reference resolution -->
+<oz-reference table="users" id={item.userId} field="fullName" orphan-fallback="Deleted user" />
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+| :--- | :--- |
+| `npx ozmoz login` | Authenticate your workstation via browser OAuth. |
+| `npx ozmoz mcp` | Configure AI agent directives and register MCP tools. |
+| `npx ozmoz init` | Initialize local `.env` and bootstrap configurations. |
+| `npx ozmoz sync` | Seal contract on Cloud Edge and compile TypeScript definitions. |
+| `npx ozmoz sync --check-only` | Offline contract and type validation (no network requests). |
+```
+eof
+
+### Résumé des éléments générés
+
+1. **`checklist_deploiement.md`** : Fournit le diagnostic complet, les points de vigilance sur les bundles et Cloud Functions, ainsi que les 3 commandes de smoke test à exécuter avant le déploiement.
+2. **`README.md`** : Totalement unifié sous la marque **ozmoZ**, avec des exemples d'écriture conformes aux règles d'intégrité (gouvernance `{ desc, role }` et vérification de `res.success`).
+
+
+# ozmoz
+
+```bash
+npx ozmoz
+```
+
+ozmoZ is the SDK and CLI behind the `oz.*` API and the `<oz-*>` tags.
+
+## Quick start
+
+Let an AI agent build for you (Claude Code, Gemini CLI, Codex CLI):
+
+```bash
+npx ozmoz start claude "your app idea"
+```
+
+Or connect your agent once, then work as usual:
+
+```bash
+npx ozmoz login     # approve once in the browser
+npx ozmoz mcp       # writes AGENTS.md / CLAUDE.md / GEMINI.md and configures the MCP server
+```
+
+## In an existing project
+
+```bash
+npm install ozmoz
+npx ozmoz init --keyApp=<KEY> --token=<TOKEN>
+npx ozmoz sync      # seals the schema and generates the contract + IDE types
+```
+
+Use `npx ozmoz sync --check-only` for an offline check.
+
+## Modes
+
+Set in `.env`:
+
+- `OZ_PROTOTYPE=true`: trial mode, everything is simulated locally (no backend call).
+- `OZ_PROTOTYPE=false`: live mode, the data contract is enforced.
+
+Run `npx ozmoz --help` for all commands.