@waelio/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waelio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# waelio CLI + UI
+
+TypeScript toolkit for building [`waelio/siteforge`](https://github.com/waelio/siteforge) from either the terminal or a browser UI.
+
+## 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
+
+## What it does
+
+- 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
+
+## Requirements
+
+- Node.js 20+
+- npm
+- git
+- Go
+
+## Install dependencies
+
+```sh
+npm install
+```
+
+## Run the UI in development
+
+```sh
+npm run dev
+```
+
+That starts:
+
+- the API/build server on `http://localhost:3000`
+- the Vite UI on `http://localhost:5173`
+
+## Build everything
+
+```sh
+npm run build
+```
+
+## Run the built UI + API server
+
+```sh
+npm start
+```
+
+## CLI commands
+
+### Check prerequisites
+
+```sh
+node dist/index.js doctor
+```
+
+### Build `siteforge`
+
+```sh
+node dist/index.js build
+```
+
+Options:
+
+- `--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
+
+### Start the local UI/API server from the CLI
+
+```sh
+node dist/index.js ui --port 3000
+```
+
+### Scaffold a Next.js + NestJS project from a blueprint
+
+```sh
+node dist/index.js scaffold ./blueprint.json --out ./sites
+```
+
+Options:
+
+- `--out <dir>` — output root (defaults to `siteforge/sites`)
+- `--no-git` — skip `git init` and the initial commit
+
+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.
+
+## Helper repos surfaced in the UI
+
+- `waelio/ustore` — storage and state patterns
+- `waelio/utils` — shared utilities and UI-friendly helpers
+- `waelio/waelio-messaging` — future real-time collaboration ideas
+
+## Localization
+
+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:
+
+`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.
+
+## 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.
+
+- 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
+
+### Local repo API
+
+- `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
+
+- 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
+
+## 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.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { DEFAULT_SITEFORGE_REPO, runBuild, runDoctor } from "./siteforge.js";
+async function main() {
+    const program = new Command();
+    program
+        .name("waelio")
+        .description("Build the waelio/siteforge website from a local checkout or fresh clone")
+        .version("0.1.0")
+        .showHelpAfterError();
+    program
+        .command("doctor")
+        .description("Check whether git, npm, and Go are installed")
+        .action(async () => {
+        await runDoctor();
+    });
+    program
+        .command("build")
+        .description("Clone and build the waelio/siteforge website")
+        .option("--repo <url>", "repository URL to build", DEFAULT_SITEFORGE_REPO)
+        .option("--ref <ref>", "branch, tag, or commit to checkout before building")
+        .option("--source <path>", "use an existing local siteforge checkout instead of cloning")
+        .option("--workdir <path>", "directory to clone into when --source is not provided")
+        .option("--dry-run", "print the build plan without executing it", false)
+        .action(async (options) => {
+        await runBuild({
+            repoUrl: options.repo,
+            ref: options.ref,
+            source: options.source,
+            workdir: options.workdir,
+            dryRun: options.dryRun,
+        });
+    });
+    program
+        .command("ui")
+        .description("Start the local web UI and API server")
+        .option("--port <number>", "port for the local server", "3000")
+        .action(async (options) => {
+        const { startServer } = await import("./server.js");
+        const port = Number(options.port);
+        if (!Number.isInteger(port) || port <= 0) {
+            throw new Error(`Invalid port: ${options.port}`);
+        }
+        await startServer({ port });
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`\nError: ${message}`);
+    process.exitCode = 1;
+});

package/dist/localRepos.d.ts

@@ -0,0 +1,29 @@
+export declare const DEFAULT_LOCAL_REPOS_ROOT: string;
+export interface LocalRepositorySummary {
+    id: string;
+    name: string;
+    owner: string;
+    relativePath: string;
+    absolutePath: string;
+}
+export interface LocalRepositoriesSnapshot {
+    root: string;
+    repositories: LocalRepositorySummary[];
+}
+export interface LocalDirectoryEntry {
+    name: string;
+    kind: "directory" | "file";
+    relativePath: string;
+    absolutePath: string;
+    hidden: boolean;
+}
+export interface LocalDirectoryListing {
+    repo: LocalRepositorySummary;
+    requestedPath: string;
+    absolutePath: string;
+    entries: LocalDirectoryEntry[];
+}
+export declare function scanLocalRepositories(root?: string): Promise<LocalRepositoriesSnapshot>;
+export declare function listLocalRepositoryDirectory(snapshot: LocalRepositoriesSnapshot, repositoryId: string, requestedPath?: string): Promise<LocalDirectoryListing>;
+export declare function sanitizeRepositoryRelativePath(value?: string): string;
+export declare function createLocalRepositoryId(relativePath: string): string;

package/dist/localRepos.js

@@ -0,0 +1,137 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+const configuredLocalReposRoot = process.env.WAELIO_LOCAL_ROOT?.trim();
+export const DEFAULT_LOCAL_REPOS_ROOT = path.resolve(configuredLocalReposRoot && configuredLocalReposRoot.length > 0
+    ? configuredLocalReposRoot
+    : "/Users/waelio/Code/GitHub");
+const IGNORED_TOP_LEVEL_NAMES = new Set([".DS_Store"]);
+const IGNORED_SECOND_LEVEL_NAMES = new Set([".build", ".git", "build", "dist", "node_modules", "tmp"]);
+const IGNORED_DIRECTORY_NAMES = new Set([".git"]);
+export async function scanLocalRepositories(root = DEFAULT_LOCAL_REPOS_ROOT) {
+    const resolvedRoot = path.resolve(root);
+    const repositories = new Map();
+    for (const candidate of await readDirectoryCandidates(resolvedRoot, IGNORED_TOP_LEVEL_NAMES)) {
+        if (await hasGitMarker(candidate.absolutePath)) {
+            const repository = createRepositorySummary(resolvedRoot, candidate.absolutePath);
+            repositories.set(repository.relativePath, repository);
+            continue;
+        }
+        for (const nestedCandidate of await readDirectoryCandidates(candidate.absolutePath, IGNORED_SECOND_LEVEL_NAMES)) {
+            if (!(await hasGitMarker(nestedCandidate.absolutePath))) {
+                continue;
+            }
+            const repository = createRepositorySummary(resolvedRoot, nestedCandidate.absolutePath);
+            repositories.set(repository.relativePath, repository);
+        }
+    }
+    return {
+        root: resolvedRoot,
+        repositories: [...repositories.values()].sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+    };
+}
+export async function listLocalRepositoryDirectory(snapshot, repositoryId, requestedPath) {
+    const repository = snapshot.repositories.find((entry) => entry.id === repositoryId);
+    if (!repository) {
+        throw new Error(`Unknown local repository id: ${repositoryId}`);
+    }
+    const sanitizedPath = sanitizeRepositoryRelativePath(requestedPath);
+    const targetPath = path.resolve(repository.absolutePath, sanitizedPath);
+    if (!isPathInsideRepository(targetPath, repository.absolutePath)) {
+        throw new Error(`Invalid path outside repository: ${requestedPath ?? ""}`);
+    }
+    const details = await stat(targetPath);
+    if (!details.isDirectory()) {
+        throw new Error(`Requested path is not a directory: ${sanitizedPath}`);
+    }
+    const dirents = await readdir(targetPath, { withFileTypes: true });
+    const entries = dirents
+        .filter((entry) => !IGNORED_DIRECTORY_NAMES.has(entry.name))
+        .map((entry) => {
+        const childRelativePath = sanitizedPath.length > 0 ? path.posix.join(sanitizedPath, entry.name) : entry.name;
+        const childAbsolutePath = path.join(targetPath, entry.name);
+        return {
+            name: entry.name,
+            kind: entry.isDirectory() ? "directory" : "file",
+            relativePath: childRelativePath,
+            absolutePath: childAbsolutePath,
+            hidden: entry.name.startsWith("."),
+        };
+    })
+        .sort((left, right) => {
+        if (left.kind !== right.kind) {
+            return left.kind === "directory" ? -1 : 1;
+        }
+        return left.name.localeCompare(right.name);
+    });
+    return {
+        repo: repository,
+        requestedPath: sanitizedPath,
+        absolutePath: targetPath,
+        entries,
+    };
+}
+export function sanitizeRepositoryRelativePath(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    const normalized = path.posix.normalize(trimmed.replace(/\\/g, "/")).replace(/^\/+/, "");
+    if (normalized === ".") {
+        return "";
+    }
+    if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+        throw new Error(`Invalid path outside repository: ${value}`);
+    }
+    return normalized;
+}
+export function createLocalRepositoryId(relativePath) {
+    return Buffer.from(relativePath, "utf8").toString("base64url");
+}
+async function readDirectoryCandidates(directoryPath, ignoredNames) {
+    try {
+        const dirents = await readdir(directoryPath, { withFileTypes: true });
+        return dirents
+            .filter((entry) => entry.isDirectory())
+            .filter((entry) => !entry.name.startsWith("."))
+            .filter((entry) => !ignoredNames.has(entry.name))
+            .map((entry) => ({
+            name: entry.name,
+            absolutePath: path.join(directoryPath, entry.name),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function hasGitMarker(directoryPath) {
+    return pathExists(path.join(directoryPath, ".git"));
+}
+function createRepositorySummary(root, absolutePath) {
+    const relativePath = path.relative(root, absolutePath);
+    const parts = relativePath.split(path.sep).filter(Boolean);
+    const owner = parts.length > 1 ? parts[0] ?? "" : "local";
+    const name = parts[parts.length - 1] ?? relativePath;
+    return {
+        id: createLocalRepositoryId(relativePath),
+        name,
+        owner,
+        relativePath,
+        absolutePath,
+    };
+}
+function isPathInsideRepository(targetPath, repositoryPath) {
+    const relative = path.relative(repositoryPath, targetPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/localRepos.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/localRepos.test.js

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { createLocalRepositoryId, listLocalRepositoryDirectory, sanitizeRepositoryRelativePath, scanLocalRepositories, } from "./localRepos.js";
+test("scanLocalRepositories returns top-level local repositories only", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "waelio-local-repos-"));
+    try {
+        await mkdir(path.join(root, "waelio", "cli", ".git"), { recursive: true });
+        await mkdir(path.join(root, "waelio", "siteforge", ".git"), { recursive: true });
+        await mkdir(path.join(root, "waelio", "siteforge", ".build", "checkouts", "nested", ".git"), {
+            recursive: true,
+        });
+        await mkdir(path.join(root, "peace2074", "peace2074.com", ".git"), { recursive: true });
+        const snapshot = await scanLocalRepositories(root);
+        assert.deepEqual(snapshot.repositories.map((repository) => repository.relativePath), ["peace2074/peace2074.com", "waelio/cli", "waelio/siteforge"]);
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+});
+test("listLocalRepositoryDirectory returns sanitized directory entries", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "waelio-local-repos-"));
+    try {
+        const repositoryRoot = path.join(root, "waelio", "cli");
+        await mkdir(path.join(repositoryRoot, ".git"), { recursive: true });
+        await mkdir(path.join(repositoryRoot, "src"), { recursive: true });
+        await writeFile(path.join(repositoryRoot, "README.md"), "# demo\n");
+        await writeFile(path.join(repositoryRoot, "src", "index.ts"), "export {};\n");
+        const snapshot = await scanLocalRepositories(root);
+        const repository = snapshot.repositories[0];
+        assert.ok(repository);
+        assert.equal(repository?.id, createLocalRepositoryId("waelio/cli"));
+        const rootListing = await listLocalRepositoryDirectory(snapshot, repository.id);
+        assert.equal(rootListing.entries[0]?.name, "src");
+        assert.equal(rootListing.entries[1]?.name, "README.md");
+        const nestedListing = await listLocalRepositoryDirectory(snapshot, repository.id, "src");
+        assert.equal(nestedListing.requestedPath, "src");
+        assert.equal(nestedListing.entries[0]?.relativePath, "src/index.ts");
+        await assert.rejects(() => listLocalRepositoryDirectory(snapshot, repository.id, "../outside"), /Invalid path outside repository/);
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+});
+test("sanitizeRepositoryRelativePath normalizes safe paths", () => {
+    assert.equal(sanitizeRepositoryRelativePath("src/components"), "src/components");
+    assert.equal(sanitizeRepositoryRelativePath("./src/../src/views"), "src/views");
+    assert.equal(sanitizeRepositoryRelativePath(""), "");
+});

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { type Server as HttpServer } from "node:http";
+export declare function startServer(options?: {
+    port?: number;
+}): Promise<HttpServer>;