@waelio/cli

TypeScript CLI + browser UI toolkit for building waelio/siteforge from the terminal or a local web interface.

🔗 Live demo: cli.waelio.workers.dev

Built with Vite 8 · TypeScript · Vue 3 · Commander.

---

✨ Features

• 🩺 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:

npx @waelio/cli --help

Or install globally:

npm install -g @waelio/cli

---

🚀 CLI Commands

waelio --help

Print the top-level help and list all available commands.

waelio doctor

Check that all required tools (git, npm, go) are installed and accessible:

waelio doctor

waelio build

Clone and build the waelio/siteforge website:

waelio build

Options:

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

Examples:

# default — clone and build waelio/siteforge
waelio build

# preview what would happen without executing
waelio build --dry-run

# build a specific branch
waelio build --ref feat/new-homepage

# build from a local checkout
waelio build --source ~/Code/GitHub/waelio/siteforge

# build a fork
waelio build --repo https://github.com/yourname/siteforge.git

waelio ui

Start the local web UI and API server:

waelio ui
waelio ui --port 4000   # default: 3011

Open http://localhost:3011 in your browser.

UI Views:

View	Description
Scaffold	Form-based generator to produce and deploy Siteforge blueprints
Public Sites	Dashboard listing scaffolded client sites served via /api/public-sites
Negotiation	Manage 2-AI negotiation sessions (kickoff, auth, status, handoff) via proxied API routes

waelio scaffold <blueprint>

Scaffold a full Next.js (frontend) + NestJS (backend) project from a Siteforge blueprint JSON:

waelio scaffold ./blueprint.json

Options:

Flag	Description	Default
--out <dir>	Output root directory	siteforge/sites
--no-git	Skip git init and the initial commit	false

Examples:

# scaffold with defaults
waelio scaffold ./blueprint.json

# 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.

---

🏛️ 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

---

🛠️ Development

Install dependencies

pnpm install

Run in development

pnpm dev

Starts concurrently:

• API server on http://localhost:3011
• Vite UI on http://localhost:5173 (proxies /api → :3011)

Build everything

pnpm run build

Run the production server

pnpm start

Quality checks

pnpm run typecheck   # tsc --noEmit + vue-tsc for the UI
pnpm test            # run *.test.ts via tsx --test
pnpm run check       # typecheck + tests

---

☁️ Deployment

The UI is deployed to Cloudflare Workers as a static site.

Deploy manually

pnpm run build
npx wrangler deploy

The wrangler.toml configuration serves the built Vue app from ui/dist:

name = "cli"
compatibility_date = "2024-12-01"

[assets]
directory = "./ui/dist"

Live URL: 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
GET	/api/negotiate/health	Check negotiation service health
POST	/api/negotiate/kickoff	Create session + authenticate prompt A + save handoff
POST	/api/negotiate/auth	Authenticate prompt A or prompt B
GET	/api/negotiate/status?sessionId=...	Fetch negotiation session status
GET	/api/negotiate/handoff?sessionId=...	Fetch shared handoff markdown

Local Repository Discovery

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

Safety rules:

• 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)

---

🌍 Localization

UI strings live in src/locals/<lang>/<lang>.json with a top-level src/locals/manifest.json.

Supported locales:

ar · de · en · es · fr · he · id · it · ru · sv · tr · zh

RTL locales (ar, he) are supported — keep them in mind when editing UI copy.

---

📚 Related Packages

Package	Description
@waelio/utils	Shared utilities and UI helpers
@waelio/ustore	Universal storage and state patterns
@waelio/agent	AI agent frontend toolkit
@waelio/sync	Real-time sync utilities

---

📄 License

MIT © Waelio