@waelio/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,16 +1,8 @@
-# waelio CLI + UI
+# @waelio/cli
 
-TypeScript toolkit for building [`waelio/siteforge`](https://github.com/waelio/siteforge) from either the terminal or a browser UI.
+TypeScript CLI + browser UI toolkit for building [`waelio/siteforge`](https://github.com/waelio/siteforge) from the terminal or a local web interface.
 
-## Recommended UI stack
-
-This repo now uses **Vite + TypeScript + Vue** for the on-screen UI.
-
-Why this stack fits well here:
-
-- **Vite** keeps development fast
-- **TypeScript** matches the rest of the repo and the build pipeline
-- **Vue** fits naturally with the broader waelio ecosystem and is quick to iterate on
+Built with **Vite + TypeScript + Vue**.
 
 ## What it does
 
@@ -28,79 +20,170 @@ Why this stack fits well here:
 - git
 - Go
 
-## Install dependencies
+## Install
+
+Run without installing:
 
 ```sh
-npm install
+npx @waelio/cli --help
 ```
 
-## Run the UI in development
+Or install globally:
 
 ```sh
-npm run dev
+npm install -g @waelio/cli
 ```
 
-That starts:
+## CLI commands
 
-- the API/build server on `http://localhost:3000`
-- the Vite UI on `http://localhost:5173`
+### `waelio --help`
 
-## Build everything
+Print the top-level help and list all available commands:
 
 ```sh
-npm run build
+waelio --help
 ```
 
-## Run the built UI + API server
+### `waelio doctor`
+
+Check that all required tools (`git`, `npm`, `go`) are installed and accessible:
 
 ```sh
-npm start
+waelio doctor
 ```
 
-## CLI commands
+### `waelio build`
+
+Clone and build the `waelio/siteforge` website:
+
+```sh
+waelio build
+```
+
+**All options:**
 
-### Check prerequisites
+```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
+```
+
+**Common examples:**
+
+```sh
+# 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 you already have
+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):
 
 ```sh
-node dist/index.js doctor
+waelio ui
 ```
 
-### Build `siteforge`
+**Options:**
 
 ```sh
-node dist/index.js build
+waelio ui --port 4000   # default port is 3000
 ```
 
-Options:
+Open `http://localhost:3000` in your browser after running this.
 
-- `--repo <url>` — repository URL to build (defaults to `waelio/siteforge`)
-- `--ref <ref>` — branch, tag, or commit to checkout before building
-- `--source <path>` — use an existing local checkout instead of cloning
-- `--workdir <path>` — directory to clone into when `--source` is not provided
-- `--dry-run` — print the build plan without executing it
+### `waelio scaffold <blueprint>`
 
-### Start the local UI/API server from the CLI
+Scaffold a full Next.js (frontend) + NestJS (backend) project from a siteforge blueprint JSON:
 
 ```sh
-node dist/index.js ui --port 3000
+waelio scaffold ./blueprint.json
 ```
 
-### Scaffold a Next.js + NestJS project from a blueprint
+**All options:**
 
 ```sh
-node dist/index.js scaffold ./blueprint.json --out ./sites
+waelio scaffold ./blueprint.json \
+  --out ./sites \   # output root directory (default: siteforge/sites)
+  --no-git          # skip git init and the initial commit
 ```
 
-Options:
+**Common examples:**
+
+```sh
+# scaffold with defaults
+waelio scaffold ./blueprint.json
 
-- `--out <dir>` — output root (defaults to `siteforge/sites`)
-- `--no-git` — skip `git init` and the initial commit
+# scaffold into a custom output directory
+waelio scaffold ./blueprint.json --out ~/projects/my-site
 
-The blueprint is a JSON file produced by siteforge that describes the project
-name, slug, and selections (pages, features, integrations, locales, roles,
-brand tones, visual styles, content models, and SEO focuses). The scaffolder
-generates a frontend (Next.js) and backend (NestJS) workspace from those
-selections.
+# scaffold without initialising a git repository
+waelio scaffold ./blueprint.json --no-git
+
+# combine options
+waelio scaffold ./blueprint.json --out ./sites --no-git
+```
+
+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
+
+### Install dependencies
+
+```sh
+npm install
+```
+
+### Run in development
+
+```sh
+npm run dev
+```
+
+Starts:
+
+- API/build server on `http://localhost:3000`
+- Vite UI on `http://localhost:5173`
+
+### Build everything
+
+```sh
+npm run build
+```
+
+### Run the built server
+
+```sh
+npm start
+```
+
+### Other scripts
+
+```sh
+npm run typecheck   # tsc --noEmit + vue-tsc for the UI
+npm test            # run *.test.ts via tsx --test
+npm run check       # typecheck + tests
+```
 
 ## Helper repos surfaced in the UI
 
@@ -118,15 +201,6 @@ locales ship by default:
 
 RTL locales (`ar`, `he`) should be considered when adding or editing UI copy.
 
-## Scripts
-
-- `npm run dev` — run the API server and Vite UI together
-- `npm run build` — build the CLI (`tsc`) and the UI (`vite build`)
-- `npm start` — run the built server (`dist/server.js`)
-- `npm run typecheck` — `tsc --noEmit` plus `vue-tsc` for the UI
-- `npm test` — run `*.test.ts` via `tsx --test`
-- `npm run check` — typecheck + tests
-
 ## Local repository discovery
 
 The UI and API now scan your local GitHub workspace and build a sanitized repository index.

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { DEFAULT_SITEFORGE_REPO, runBuild, runDoctor } from "./siteforge.js";
+import { scaffold } from "./scaffold.js";
 async function main() {
     const program = new Command();
     program
@@ -43,6 +44,19 @@ async function main() {
         }
         await startServer({ port });
     });
+    program
+        .command("scaffold <blueprint>")
+        .description("Scaffold a Next.js + NestJS project from a siteforge blueprint JSON")
+        .option("--out <dir>", "output root (default: siteforge/sites)")
+        .option("--no-git", "skip git init / initial commit")
+        .action(async (blueprint, options) => {
+        const result = await scaffold({
+            blueprintPath: blueprint,
+            outRoot: options.out,
+            initGit: options.git,
+        });
+        console.log(`Scaffolded "${result.slug}" (${result.pageCount} pages) at:\n  ${result.outDir}`);
+    });
     await program.parseAsync(process.argv);
 }
 main().catch((error) => {

package/dist/scaffold.d.ts

@@ -0,0 +1,35 @@
+export interface BlueprintSelections {
+    selectedPages?: string[];
+    selectedFeatures?: string[];
+    selectedIntegrations?: string[];
+    selectedLocales?: string[];
+    selectedRoles?: string[];
+    selectedBrandTones?: string[];
+    selectedVisualStyles?: string[];
+    selectedContentModels?: string[];
+    selectedSEOFocuses?: string[];
+}
+export interface Blueprint {
+    id?: string;
+    createdAt?: string;
+    projectName?: string;
+    slug?: string;
+    selections?: BlueprintSelections;
+}
+export interface ScaffoldOptions {
+    blueprintPath: string;
+    outRoot?: string;
+    initGit?: boolean;
+}
+export interface ScaffoldFromBlueprintOptions {
+    blueprint: Blueprint;
+    outRoot?: string;
+    initGit?: boolean;
+}
+export interface ScaffoldResult {
+    slug: string;
+    outDir: string;
+    pageCount: number;
+}
+export declare function scaffoldFromBlueprint(options: ScaffoldFromBlueprintOptions): Promise<ScaffoldResult>;
+export declare function scaffold(options: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/scaffold.js

@@ -0,0 +1,333 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const DEFAULT_OUT_ROOT = "/Users/waelio/Code/GitHub/waelio/siteforge/sites";
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        || "site";
+}
+function pageToRoute(name) {
+    const trimmed = name.trim();
+    if (!trimmed || trimmed.toLowerCase() === "home")
+        return "/";
+    return "/" + slugify(trimmed);
+}
+function pagePath(route) {
+    if (route === "/")
+        return "app/page.tsx";
+    return `app${route}/page.tsx`;
+}
+async function writeFileEnsured(filePath, content) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, "utf8");
+}
+function frontendPackageJson(name) {
+    return JSON.stringify({
+        name: `${name}-frontend`,
+        version: "0.0.1",
+        private: true,
+        scripts: {
+            dev: "next dev -p 3001",
+            build: "next build",
+            start: "next start -p 3001",
+            lint: "next lint",
+        },
+        dependencies: {
+            next: "^14.2.0",
+            react: "^18.3.1",
+            "react-dom": "^18.3.1",
+        },
+        devDependencies: {
+            typescript: "^5.4.0",
+            "@types/node": "^20.0.0",
+            "@types/react": "^18.3.0",
+            "@types/react-dom": "^18.3.0",
+        },
+    }, null, 2);
+}
+const NEXT_TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "baseUrl": ".",
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}
+`;
+const NEXT_CONFIG = `/** @type {import('next').NextConfig} */
+const nextConfig = { reactStrictMode: true };
+module.exports = nextConfig;
+`;
+const NEXT_ENV_DTS = `/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+`;
+function rootLayout(name, pages) {
+    const navItems = pages
+        .map((p) => `<a href="${p.route}" style={{ marginRight: 16 }}>${p.name}</a>`)
+        .join("\n          ");
+    return `import type { ReactNode } from "react";
+
+export const metadata = {
+  title: "${name}",
+  description: "Generated by waelio/cli + siteforge",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body style={{ fontFamily: "system-ui, sans-serif", margin: 0 }}>
+        <header style={{ padding: 16, borderBottom: "1px solid #eee" }}>
+          <strong>${name}</strong>
+          <nav style={{ marginTop: 8 }}>
+          ${navItems}
+          </nav>
+        </header>
+        <main style={{ padding: 24 }}>{children}</main>
+      </body>
+    </html>
+  );
+}
+`;
+}
+function pageComponent(pageName, projectName) {
+    const isHome = pageName.toLowerCase() === "home" || pageName === "/";
+    const heading = isHome ? projectName : pageName;
+    return `export default function Page() {
+  return (
+    <section>
+      <h1>${heading}</h1>
+      <p>Generated ${pageName} page.</p>
+    </section>
+  );
+}
+`;
+}
+function backendPackageJson(name) {
+    return JSON.stringify({
+        name: `${name}-backend`,
+        version: "0.0.1",
+        private: true,
+        scripts: {
+            start: "node dist/main.js",
+            "start:dev": "ts-node-dev --respawn src/main.ts",
+            build: "tsc -p tsconfig.json",
+        },
+        dependencies: {
+            "@nestjs/common": "^10.3.0",
+            "@nestjs/core": "^10.3.0",
+            "@nestjs/platform-express": "^10.3.0",
+            "reflect-metadata": "^0.2.0",
+            rxjs: "^7.8.0",
+        },
+        devDependencies: {
+            "@types/node": "^20.0.0",
+            "ts-node-dev": "^2.0.0",
+            typescript: "^5.4.0",
+        },
+    }, null, 2);
+}
+const NEST_TSCONFIG = `{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es2021",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+`;
+function nestMain(modules) {
+    const moduleList = modules.map((m) => `"${m}"`).join(", ");
+    return `import "reflect-metadata";
+import { NestFactory } from "@nestjs/core";
+import { AppModule } from "./app.module.js";
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.enableCors();
+  const port = Number(process.env.PORT ?? 3002);
+  await app.listen(port);
+  console.log(\`backend listening on http://localhost:\${port}\`);
+  console.log("modules:", [${moduleList}]);
+}
+bootstrap();
+`;
+}
+const NEST_APP_MODULE = `import { Module } from "@nestjs/common";
+import { HealthController } from "./health.controller.js";
+
+@Module({
+  controllers: [HealthController],
+})
+export class AppModule {}
+`;
+const NEST_HEALTH_CONTROLLER = `import { Controller, Get } from "@nestjs/common";
+
+@Controller("health")
+export class HealthController {
+  @Get()
+  ok() {
+    return { status: "ok", at: new Date().toISOString() };
+  }
+}
+`;
+function rootReadme(name, slug, blueprint) {
+    const sel = blueprint.selections ?? {};
+    const list = (xs) => xs && xs.length ? xs.map((x) => `- ${x}`).join("\n") : "_(none)_";
+    return `# ${name}
+
+Generated by **waelio/cli** from a siteforge blueprint.
+
+- **Slug:** \`${slug}\`
+- **Generated:** ${new Date().toISOString()}
+
+## Layout
+
+- \`frontend/\` — Next.js app (port 3001)
+- \`backend/\` — NestJS app (port 3002)
+
+## Run
+
+\`\`\`bash
+cd frontend && npm install && npm run dev
+cd ../backend && npm install && npm run start:dev
+\`\`\`
+
+## Blueprint selections
+
+### Pages
+${list(sel.selectedPages)}
+
+### Features
+${list(sel.selectedFeatures)}
+
+### Integrations
+${list(sel.selectedIntegrations)}
+
+### Locales
+${list(sel.selectedLocales)}
+
+### Roles
+${list(sel.selectedRoles)}
+`;
+}
+const ROOT_GITIGNORE = `node_modules/
+dist/
+.next/
+.env
+.env.local
+*.log
+`;
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function uniqueOutDir(outRoot, slug) {
+    const base = path.join(outRoot, slug);
+    if (!(await pathExists(base)))
+        return base;
+    for (let i = 2; i < 1000; i++) {
+        const candidate = path.join(outRoot, `${slug}-${i}`);
+        if (!(await pathExists(candidate)))
+            return candidate;
+    }
+    throw new Error(`Unable to find a free output directory for slug "${slug}"`);
+}
+export async function scaffoldFromBlueprint(options) {
+    const blueprint = options.blueprint;
+    const projectName = blueprint.projectName?.trim() || "Siteforge Project";
+    const slugBase = slugify(blueprint.slug || projectName);
+    const outRoot = options.outRoot || DEFAULT_OUT_ROOT;
+    const outDir = await uniqueOutDir(outRoot, slugBase);
+    const slug = path.basename(outDir);
+    return writeScaffold(blueprint, projectName, slug, outDir, options.initGit);
+}
+export async function scaffold(options) {
+    const raw = await readFile(options.blueprintPath, "utf8");
+    const blueprint = JSON.parse(raw);
+    return scaffoldFromBlueprint({
+        blueprint,
+        outRoot: options.outRoot,
+        initGit: options.initGit,
+    });
+}
+async function writeScaffold(blueprint, projectName, slug, outDir, initGit) {
+    const sel = blueprint.selections ?? {};
+    const pageNames = Array.from(new Set([
+        "Home",
+        ...(sel.selectedPages ?? []),
+    ]));
+    const pages = pageNames.map((name) => ({ name, route: pageToRoute(name) }));
+    // Frontend
+    await writeFileEnsured(path.join(outDir, "frontend/package.json"), frontendPackageJson(slug));
+    await writeFileEnsured(path.join(outDir, "frontend/tsconfig.json"), NEXT_TSCONFIG);
+    await writeFileEnsured(path.join(outDir, "frontend/next.config.js"), NEXT_CONFIG);
+    await writeFileEnsured(path.join(outDir, "frontend/next-env.d.ts"), NEXT_ENV_DTS);
+    await writeFileEnsured(path.join(outDir, "frontend/app/layout.tsx"), rootLayout(projectName, pages));
+    for (const page of pages) {
+        await writeFileEnsured(path.join(outDir, "frontend", pagePath(page.route)), pageComponent(page.name, projectName));
+    }
+    // Backend
+    const features = sel.selectedFeatures ?? [];
+    const modules = ["Health", ...features];
+    await writeFileEnsured(path.join(outDir, "backend/package.json"), backendPackageJson(slug));
+    await writeFileEnsured(path.join(outDir, "backend/tsconfig.json"), NEST_TSCONFIG);
+    await writeFileEnsured(path.join(outDir, "backend/src/main.ts"), nestMain(modules));
+    await writeFileEnsured(path.join(outDir, "backend/src/app.module.ts"), NEST_APP_MODULE);
+    await writeFileEnsured(path.join(outDir, "backend/src/health.controller.ts"), NEST_HEALTH_CONTROLLER);
+    // Root
+    await writeFileEnsured(path.join(outDir, "README.md"), rootReadme(projectName, slug, blueprint));
+    await writeFileEnsured(path.join(outDir, ".gitignore"), ROOT_GITIGNORE);
+    await writeFileEnsured(path.join(outDir, "blueprint.json"), JSON.stringify(blueprint, null, 2));
+    if (initGit !== false) {
+        try {
+            await execFileAsync("git", ["init", "-q"], { cwd: outDir });
+            await execFileAsync("git", ["add", "."], { cwd: outDir });
+            await execFileAsync("git", ["commit", "-q", "-m", "scaffold from siteforge blueprint"], {
+                cwd: outDir,
+                env: {
+                    ...process.env,
+                    GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME ?? "waelio-cli",
+                    GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL ?? "cli@waelio.dev",
+                    GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME ?? "waelio-cli",
+                    GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL ?? "cli@waelio.dev",
+                },
+            });
+        }
+        catch (err) {
+            // Non-fatal: leave folder unversioned if git init fails.
+            console.warn(`git init skipped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { slug, outDir, pageCount: pages.length };
+}