@waelio/cli 0.1.9 → 0.1.11

package/README.md

@@ -1,26 +1,29 @@
 # @waelio/cli
 
-TypeScript CLI + browser UI toolkit for building [`waelio/siteforge`](https://github.com/waelio/siteforge) from the terminal or a local web interface.
+[![npm version](https://img.shields.io/npm/v/@waelio/cli.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@waelio/cli)
+[![license](https://img.shields.io/npm/l/@waelio/cli.svg?style=flat-square)](./LICENSE)
+[![node](https://img.shields.io/node/v/@waelio/cli.svg?style=flat-square)](https://nodejs.org)
 
-Built with **Vite + TypeScript + Vue**.
+> TypeScript CLI + browser UI toolkit for building [`waelio/siteforge`](https://github.com/waelio/siteforge) from the terminal or a local web interface.
 
-## What it does
+🔗 **Live demo:** [cli.waelio.workers.dev](https://cli.waelio.workers.dev)
 
-- checks that required local tools are installed
-- previews the build plan before running it
-- clones `waelio/siteforge` into a working directory
-- installs dependencies with `npm ci`
-- runs `npm run build`
-- shows the full workflow in a browser UI with live logs
+Built with **Vite 8 · TypeScript · Vue 3 · Commander**.
 
-## Requirements
+---
 
-- Node.js 20+
-- npm
-- git
-- Go
+## ✨ Features
 
-## Install
+- 🩺 **Doctor** — checks that required local tools are installed
+- 📋 **Dry-run** — previews the build plan before running it
+- 🔧 **Build** — clones `waelio/siteforge`, installs deps, and runs the build
+- 🏗️ **Scaffold** — generates full Next.js + NestJS projects from a blueprint JSON
+- 🖥️ **Browser UI** — a Vue dashboard with live logs, scaffold forms, and public site listings
+- 🌐 **12 locales** — `ar` `de` `en` `es` `fr` `he` `id` `it` `ru` `sv` `tr` `zh` (RTL-ready)
+
+---
+
+## 📦 Install
 
 Run without installing:
 
@@ -34,15 +37,13 @@ Or install globally:
 npm install -g @waelio/cli
 ```
 
-## CLI commands
+---
 
-### `waelio --help`
+## 🚀 CLI Commands
 
-Print the top-level help and list all available commands:
+### `waelio --help`
 
-```sh
-waelio --help
-```
+Print the top-level help and list all available commands.
 
 ### `waelio doctor`
 
@@ -60,18 +61,17 @@ Clone and build the `waelio/siteforge` website:
 waelio build
 ```
 
-**All options:**
+**Options:**
 
-```sh
-waelio build \
-  --repo https://github.com/waelio/siteforge.git \  # custom repository URL (default: waelio/siteforge)
-  --ref  main \                                      # branch, tag, or commit to checkout
-  --source ./my-local-siteforge \                    # skip cloning, use an existing checkout
-  --workdir ./build-tmp \                            # directory to clone into
-  --dry-run                                          # print the plan without running anything
-```
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--repo <url>` | Custom repository URL | `waelio/siteforge` |
+| `--ref <ref>` | Branch, tag, or commit to checkout | `main` |
+| `--source <path>` | Skip cloning, use an existing checkout | — |
+| `--workdir <path>` | Directory to clone into | `./tmp` |
+| `--dry-run` | Print the plan without running anything | `false` |
 
-**Common examples:**
+**Examples:**
 
 ```sh
 # default — clone and build waelio/siteforge
@@ -83,153 +83,204 @@ waelio build --dry-run
 # build a specific branch
 waelio build --ref feat/new-homepage
 
-# build from a local checkout you already have
+# build from a local checkout
 waelio build --source ~/Code/GitHub/waelio/siteforge
 
-# clone into a custom directory
-waelio build --workdir /tmp/siteforge-build
-
 # build a fork
 waelio build --repo https://github.com/yourname/siteforge.git
 ```
 
 ### `waelio ui`
 
-Start the local web UI and API server (browser dashboard with live build logs and a multi-view interface):
+Start the local web UI and API server:
 
 ```sh
 waelio ui
+waelio ui --port 4000   # default: 3000
 ```
 
-**UI Features:**
-- **Scaffold View:** Form-based generator to produce and deploy Siteforge blueprints to webhooks.
-- **Public Sites View:** A dedicated dashboard for listing and accessing successfully scaffolded client sites served via the `/api/public-sites` route.
+Open `http://localhost:3000` in your browser.
 
-**Options:**
+**UI Views:**
 
-```sh
-waelio ui --port 4000   # default port is 3000
-```
-
-Open `http://localhost:3000` in your browser after running this.
+| View | Description |
+|------|-------------|
+| **Scaffold** | Form-based generator to produce and deploy Siteforge blueprints |
+| **Public Sites** | Dashboard listing scaffolded client sites served via `/api/public-sites` |
 
 ### `waelio scaffold <blueprint>`
 
-Scaffold a full Next.js (frontend) + NestJS (backend) project from a siteforge blueprint JSON:
+Scaffold a full Next.js (frontend) + NestJS (backend) project from a Siteforge blueprint JSON:
 
 ```sh
 waelio scaffold ./blueprint.json
 ```
 
-**All options:**
+**Options:**
 
-```sh
-waelio scaffold ./blueprint.json \
-  --out ./sites \   # output root directory (default: siteforge/sites)
-  --no-git          # skip git init and the initial commit
-```
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--out <dir>` | Output root directory | `siteforge/sites` |
+| `--no-git` | Skip `git init` and the initial commit | `false` |
 
-**Common examples:**
+**Examples:**
 
 ```sh
 # scaffold with defaults
 waelio scaffold ./blueprint.json
 
-# scaffold into a custom output directory
+# scaffold into a custom directory
 waelio scaffold ./blueprint.json --out ~/projects/my-site
 
 # scaffold without initialising a git repository
 waelio scaffold ./blueprint.json --no-git
+```
+
+The blueprint JSON describes the project name, slug, pages, features, integrations, locales, roles, brand tones, visual styles, content models, and SEO focuses. The scaffolder generates both workspaces from those selections.
 
-# combine options
-waelio scaffold ./blueprint.json --out ./sites --no-git
+---
+
+## 🏛️ Project Structure
+
+```
+@waelio/cli
+├── src/
+│   ├── index.ts          # CLI entry point (Commander)
+│   ├── server.ts         # Express API server
+│   ├── siteforge.ts      # Build orchestration
+│   ├── scaffold.ts       # Blueprint scaffolder
+│   ├── localRepos.ts     # Local repo discovery
+│   └── locals/           # i18n locale files (12 languages)
+├── ui/
+│   ├── src/
+│   │   ├── App.vue       # Root Vue component
+│   │   └── views/        # ScaffoldView, PublicSitesView
+│   └── dist/             # Built static assets
+├── templates/            # Multi-framework scaffold templates
+├── public-sites/         # Scaffolded demo sites (acme-dental, agent-007, e2e-test-site)
+├── wrangler.toml         # Cloudflare Workers deployment config
+├── vite.config.ts        # Vite build config
+└── package.json
 ```
 
-The blueprint JSON is produced by siteforge and describes the project name, slug,
-pages, features, integrations, locales, roles, brand tones, visual styles,
-content models, and SEO focuses. The scaffolder generates both workspaces from
-those selections.
+---
 
-## Development
+## 🛠️ Development
 
 ### Install dependencies
 
 ```sh
-npm install
+pnpm install
 ```
 
 ### Run in development
 
 ```sh
-npm run dev
+pnpm dev
 ```
 
-Starts:
+Starts concurrently:
 
-- API/build server on `http://localhost:3000`
-- Vite UI on `http://localhost:5173`
+- **API server** on `http://localhost:3000`
+- **Vite UI** on `http://localhost:5173` (proxies `/api` → `:3000`)
 
 ### Build everything
 
 ```sh
-npm run build
+pnpm run build
+```
+
+### Run the production server
+
+```sh
+pnpm start
 ```
 
-### Run the built server
+### Quality checks
 
 ```sh
-npm start
+pnpm run typecheck   # tsc --noEmit + vue-tsc for the UI
+pnpm test            # run *.test.ts via tsx --test
+pnpm run check       # typecheck + tests
 ```
 
-### Other scripts
+---
+
+## ☁️ Deployment
+
+The UI is deployed to **Cloudflare Workers** as a static site.
+
+### Deploy manually
 
 ```sh
-npm run typecheck   # tsc --noEmit + vue-tsc for the UI
-npm test            # run *.test.ts via tsx --test
-npm run check       # typecheck + tests
+pnpm run build
+npx wrangler deploy
 ```
 
-## Helper repos surfaced in the UI
+The `wrangler.toml` configuration serves the built Vue app from `ui/dist`:
+
+```toml
+name = "cli"
+compatibility_date = "2024-12-01"
+
+[assets]
+directory = "./ui/dist"
+```
+
+**Live URL:** [https://cli.waelio.workers.dev](https://cli.waelio.workers.dev)
+
+---
+
+## 🔌 API Endpoints
+
+### Build & Scaffold
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/build` | Trigger a siteforge build |
+| `POST` | `/api/scaffold` | Scaffold from a blueprint |
+| `GET` | `/api/public-sites` | List scaffolded demo sites |
+
+### Local Repository Discovery
 
-- `waelio/ustore` — storage and state patterns
-- `waelio/utils` — shared utilities and UI-friendly helpers
-- `waelio/waelio-messaging` — future real-time collaboration ideas
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/local-repos` | Returns the local repository index |
+| `GET` | `/api/local-repos/tree?repoId=...&path=...` | Browse a repo's file tree |
 
-## Localization
+**Safety rules:**
 
-UI strings are stored as per-locale JSON files under `src/locals/<lang>/<lang>.json`,
-with a top-level `src/locals/manifest.json` summarizing the set. The following
-locales ship by default:
+- Repository IDs map to scanned local repos only
+- Folder browsing is restricted to paths inside the selected repository
+- Path traversal (`..`) is rejected
+- `.git` directories are hidden from listings
+- Default scan root: `~/Code/GitHub` (override with `WAELIO_LOCAL_ROOT`)
 
-`ar`, `de`, `en`, `es`, `fr`, `he`, `id`, `it`, `ru`, `sv`, `tr`, `zh`
+---
 
-RTL locales (`ar`, `he`) should be considered when adding or editing UI copy.
+## 🌍 Localization
 
-## Local repository discovery
+UI strings live in `src/locals/<lang>/<lang>.json` with a top-level `src/locals/manifest.json`.
 
-The UI and API now scan your local GitHub workspace and build a sanitized repository index.
+Supported locales:
 
-- default local root: `/Users/waelio/Code/GitHub`
-- override with `WAELIO_LOCAL_ROOT`
-- top-level repositories are included
-- nested build/checkouts such as `.build`, `node_modules`, `dist`, and `.git` internals are excluded from discovery
+`ar` · `de` · `en` · `es` · `fr` · `he` · `id` · `it` · `ru` · `sv` · `tr` · `zh`
 
-### Local repo API
+> RTL locales (`ar`, `he`) are supported — keep them in mind when editing UI copy.
 
-- `GET /api/local-repos` — returns the compiled local repository list
-- `GET /api/local-repos/tree?repoId=...&path=...` — returns a sanitized physical folder listing for a selected local repository
+---
 
-### Safety rules
+## 📚 Related Packages
 
-- repository IDs map to scanned local repos only
-- folder browsing is restricted to paths inside the selected repository
-- path traversal such as `..` is rejected
-- `.git` directories are hidden from the served listing
+| Package | Description |
+|---------|-------------|
+| [`@waelio/utils`](https://www.npmjs.com/package/@waelio/utils) | Shared utilities and UI helpers |
+| [`@waelio/ustore`](https://www.npmjs.com/package/@waelio/ustore) | Universal storage and state patterns |
+| [`@waelio/agent`](https://www.npmjs.com/package/@waelio/agent) | AI agent frontend toolkit |
+| [`@waelio/sync`](https://www.npmjs.com/package/@waelio/sync) | Real-time sync utilities |
 
-## Notes
+---
 
-- The default repository URL is `https://github.com/waelio/siteforge.git`.
-- A custom workdir can be used when you want a persistent local checkout.
-- If `source` is provided, cloning is skipped and the existing checkout is built directly.
+## 📄 License
 
-- [https://waelio.com/packages/@waelio/cli](https://waelio.com/packages/@waelio/cli)
+[MIT](./LICENSE) © [Waelio](https://waelio.com)

package/dist/scaffold.js

@@ -308,6 +308,58 @@ ${list(sel.selectedLocales)}
 ${list(sel.selectedRoles)}
 `;
 }
+function rootIndexHtml(name, slug) {
+    return `<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>${name}</title>
+        <style>
+            :root { color-scheme: light dark; }
+            body {
+                font-family: Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+                margin: 0;
+                min-height: 100vh;
+                display: grid;
+                place-items: center;
+                background: #0b1220;
+                color: #e5e7eb;
+            }
+            main {
+                width: min(760px, calc(100% - 2rem));
+                background: rgba(17, 24, 39, 0.92);
+                border: 1px solid rgba(148, 163, 184, 0.35);
+                border-radius: 14px;
+                padding: 1.2rem 1.25rem;
+            }
+            h1 { margin: 0 0 0.4rem; font-size: 1.25rem; }
+            p { margin: 0.35rem 0; line-height: 1.45; }
+            code {
+                background: rgba(148, 163, 184, 0.18);
+                padding: 0.12rem 0.4rem;
+                border-radius: 0.4rem;
+            }
+            ul { margin: 0.8rem 0 0; padding-left: 1.1rem; }
+            a { color: #93c5fd; }
+        </style>
+    </head>
+    <body>
+        <main>
+            <h1>${name}</h1>
+            <p>This scaffold was generated by <code>@waelio/cli</code>.</p>
+            <p>Project slug: <code>${slug}</code></p>
+            <p>Run the generated apps locally:</p>
+            <ul>
+                <li>Frontend source: <code>frontend/</code> (Next.js, port 3001)</li>
+                <li>Backend source: <code>backend/</code> (NestJS, port 3002)</li>
+                <li>Details: <a href="./README.md">README.md</a></li>
+            </ul>
+        </main>
+    </body>
+</html>
+`;
+}
 const ROOT_GITIGNORE = `node_modules/
 dist/
 .next/
@@ -428,6 +480,7 @@ async function writeScaffold(blueprint, projectName, slug, outDir, initGit) {
     }
     // Root
     await writeFileEnsured(path.join(outDir, "README.md"), rootReadme(projectName, slug, blueprint));
+    await writeFileEnsured(path.join(outDir, "index.html"), rootIndexHtml(projectName, slug));
     await writeFileEnsured(path.join(outDir, ".gitignore"), ROOT_GITIGNORE);
     await writeFileEnsured(path.join(outDir, "blueprint.json"), JSON.stringify(blueprint, null, 2));
     if (initGit !== false) {

package/dist/server.d.ts

@@ -1,4 +1,18 @@
 import { type Server as HttpServer } from "node:http";
+import { type Blueprint } from "./scaffold.js";
+interface ResolvedScaffoldRequest {
+    blueprint: Blueprint;
+    outRoot: string;
+    initGit: boolean;
+}
+interface ScaffoldPayloadResolution {
+    mode: "none" | "scaffold" | "invalid";
+    request?: ResolvedScaffoldRequest;
+    error?: string;
+}
+export declare function resolveScaffoldRequestPayload(payload: unknown, defaultOutRoot?: string): ScaffoldPayloadResolution;
 export declare function startServer(options?: {
     port?: number;
 }): Promise<HttpServer>;
+export declare function listPublicSites(rootDirectory?: string): Promise<string[]>;
+export {};