polyforge-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,65 @@
+# PolyForge Scaffold CLI
+
+PolyForge is a hybrid full-stack scaffold CLI for `go-gin` and `springboot`.
+CLI command remains `scaffold`.
+
+## Install
+
+```bash
+# one-off run
+npx polyforge-cli@latest list
+
+# global install
+npm i -g polyforge-cli
+scaffold list
+```
+
+## Commands
+
+```bash
+npm run build
+node dist/index.js doctor
+node dist/index.js create my-app
+node dist/index.js list
+npm run smoke:e2e
+```
+
+### create options
+
+- `--frontend <react|vue|none>`
+- `--backend <go-gin|springboot>`
+- `--modules <python-worker,worker-go,gateway-bff,python-ai,grpc-service,mq,cache-redis,observability,auth-center>`
+- `--data <mysql,postgresql,redis,sqlite,mongodb,none>`
+- `--pm <pnpm|npm|yarn>`
+- `--install`
+- `--git`
+- `--docker`
+- `--yes`
+
+### doctor options
+
+- `--backend <go-gin|springboot>`
+- `--modules <python-worker,worker-go,gateway-bff,python-ai,grpc-service,mq,cache-redis,observability,auth-center>`
+- `--data <mysql,postgresql,redis,sqlite,mongodb,none>`
+
+## Development
+
+```bash
+npm run lint
+npm run test
+npm run build
+```
+
+## Publish To npm
+
+```bash
+npm login
+npm publish
+```
+
+## Frontend Auto-Wiring
+
+- React/Vue templates include `.env.example` with API/BFF base URLs.
+- Vite dev server proxy routes `/api` -> backend API and `/bff` -> gateway-bff.
+- Frontend page includes demo requests for `/api/v1/ping` and `/bff/ping` with `X-Trace-Id`.
+- Frontend templates include `src/api/request.ts` (timeout/retry/error mapping), `src/api/services/*`, and `src/api/client.ts`.

package/dist/commands/create.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCreate = runCreate;
+const prompts_1 = require("../core/prompts");
+const renderer_1 = require("../core/renderer");
+const validator_1 = require("../core/validator");
+const installer_1 = require("../core/installer");
+const git_1 = require("../core/git");
+function printResolvedConfigSummary(options, config) {
+    const defaulted = [];
+    if (options.frontend === undefined)
+        defaulted.push(`frontend=${config.frontend}`);
+    if (options.backend === undefined)
+        defaulted.push(`backend=${config.backendMain}`);
+    if (options.modules === undefined)
+        defaulted.push(`modules=${config.extraModules.join(",") || "none"}`);
+    if (options.data === undefined)
+        defaulted.push(`data=${config.dataModules.join(",")}`);
+    if (options.pm === undefined)
+        defaulted.push(`pm=${config.packageManager}`);
+    if (options.install === undefined)
+        defaulted.push(`install=${String(config.installDeps)}`);
+    if (options.git === undefined)
+        defaulted.push(`git=${String(config.initGit)}`);
+    if (options.docker === undefined)
+        defaulted.push(`docker=${String(config.docker)}`);
+    if (options.yes && defaulted.length > 0) {
+        console.log(`[scaffold] --yes defaults applied: ${defaulted.join(" | ")}`);
+    }
+}
+async function runCreate(projectName, options) {
+    const config = await (0, prompts_1.resolveCreateConfig)(projectName, options);
+    printResolvedConfigSummary(options, config);
+    const validation = (0, validator_1.validateConfig)(config);
+    if (!validation.valid) {
+        throw new Error(`Invalid configuration:\n- ${validation.errors.join("\n- ")}`);
+    }
+    for (const warning of validation.warnings) {
+        console.warn(`[warning] ${warning}`);
+    }
+    await (0, renderer_1.renderProject)(config);
+    await (0, installer_1.maybeInstallDeps)(config);
+    await (0, git_1.maybeInitGit)(config);
+    console.log(`[scaffold] project created: ${config.targetDir}`);
+    console.log("[scaffold] next: cd <project> && npm run check && npm run dev");
+}

package/dist/commands/doctor.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDoctorAdvice = buildDoctorAdvice;
+exports.runDoctor = runDoctor;
+const child_process_1 = require("child_process");
+const config_1 = require("../types/config");
+const validator_1 = require("../core/validator");
+function check(name, cmd, args) {
+    const res = (0, child_process_1.spawnSync)(cmd, args, { encoding: "utf8" });
+    if (res.status === 0) {
+        return {
+            name,
+            ok: true,
+            output: (res.stdout || res.stderr || "ok").trim(),
+        };
+    }
+    return {
+        name,
+        ok: false,
+        output: (res.stderr || res.stdout || "missing").trim(),
+    };
+}
+function parseTargets(options) {
+    const backend = options.backend && config_1.BACKENDS.includes(options.backend) ? options.backend : undefined;
+    const modules = (0, validator_1.parseCsv)(options.modules).filter((item) => config_1.EXTRA_MODULES.includes(item));
+    const data = (0, validator_1.parseCsv)(options.data).filter((item) => config_1.DATA_MODULES.includes(item));
+    return { backend, modules, data };
+}
+function has(checks, name) {
+    return checks[name]?.ok ?? false;
+}
+function buildDoctorAdvice(checks, options) {
+    const targets = parseTargets(options);
+    const advice = [];
+    if (targets.backend === "go-gin") {
+        advice.push(has(checks, "go")
+            ? { label: "go-gin", status: "ok", detail: "Go toolchain detected." }
+            : { label: "go-gin", status: "warn", detail: "Install Go 1.22+ for go-gin templates." });
+    }
+    if (targets.backend === "springboot") {
+        advice.push(has(checks, "java")
+            ? { label: "springboot", status: "ok", detail: "Java runtime detected." }
+            : { label: "springboot", status: "warn", detail: "Install JDK 17+ for Spring Boot templates." });
+        advice.push(has(checks, "mvn")
+            ? { label: "maven", status: "ok", detail: "Maven detected." }
+            : { label: "maven", status: "warn", detail: "Install Maven 3.9+ to run spring build/test." });
+    }
+    if (targets.modules.includes("python-worker")) {
+        advice.push(has(checks, "python3")
+            ? { label: "python-worker", status: "ok", detail: "Python 3 runtime detected." }
+            : { label: "python-worker", status: "warn", detail: "Install Python 3.10+ for worker module." });
+    }
+    if (targets.modules.includes("worker-go")) {
+        advice.push(has(checks, "go")
+            ? { label: "worker-go", status: "ok", detail: "Go toolchain detected for worker-go module." }
+            : { label: "worker-go", status: "warn", detail: "Install Go 1.22+ for worker-go module." });
+    }
+    if (targets.modules.includes("gateway-bff")) {
+        advice.push(has(checks, "node") && has(checks, "npm")
+            ? { label: "gateway-bff", status: "ok", detail: "Node.js and npm detected for gateway-bff." }
+            : { label: "gateway-bff", status: "warn", detail: "Install Node.js 18+ and npm for gateway-bff module." });
+    }
+    if (targets.modules.includes("python-ai")) {
+        advice.push(has(checks, "python3")
+            ? { label: "python-ai", status: "ok", detail: "Python detected for python-ai module." }
+            : { label: "python-ai", status: "warn", detail: "Install Python 3.10+ for python-ai module." });
+    }
+    if (targets.modules.includes("grpc-service")) {
+        advice.push(has(checks, "protoc")
+            ? { label: "grpc-service", status: "ok", detail: "protoc detected for gRPC contract generation." }
+            : { label: "grpc-service", status: "warn", detail: "Install protoc for gRPC code generation." });
+    }
+    if (targets.modules.includes("mq")) {
+        advice.push(has(checks, "docker")
+            ? { label: "mq", status: "ok", detail: "Docker detected for local MQ brokers." }
+            : { label: "mq", status: "warn", detail: "Install Docker to run Kafka/RabbitMQ/NATS locally." });
+    }
+    if (targets.modules.includes("cache-redis")) {
+        advice.push(has(checks, "docker")
+            ? { label: "cache-redis", status: "ok", detail: "Docker detected for local Redis cache service." }
+            : { label: "cache-redis", status: "warn", detail: "Install Docker or run Redis manually." });
+    }
+    if (targets.modules.includes("observability")) {
+        advice.push(has(checks, "docker")
+            ? { label: "observability", status: "ok", detail: "Docker detected for Prometheus/Grafana stack." }
+            : { label: "observability", status: "warn", detail: "Install Docker for local observability stack." });
+    }
+    if (targets.modules.includes("auth-center")) {
+        advice.push({
+            label: "auth-center",
+            status: "ok",
+            detail: "Remember to configure JWT secrets and OAuth clients before production.",
+        });
+    }
+    if (targets.data.some((item) => item !== "none")) {
+        advice.push(has(checks, "docker")
+            ? { label: "data-services", status: "ok", detail: "Docker detected for local DB/cache containers." }
+            : { label: "data-services", status: "warn", detail: "Docker not found; run data services manually or install Docker Desktop." });
+    }
+    return advice;
+}
+async function runDoctor(options = {}) {
+    const checksList = [
+        check("node", "node", ["-v"]),
+        check("npm", "npm", ["-v"]),
+        check("go", "go", ["version"]),
+        check("java", "java", ["-version"]),
+        check("mvn", "mvn", ["-v"]),
+        check("python3", "python3", ["--version"]),
+        check("git", "git", ["--version"]),
+        check("docker", "docker", ["--version"]),
+        check("protoc", "protoc", ["--version"]),
+    ];
+    const checks = Object.fromEntries(checksList.map((item) => [item.name, item]));
+    let failed = 0;
+    for (const item of checksList) {
+        if (!item.ok)
+            failed += 1;
+        const status = item.ok ? "OK" : "MISSING";
+        console.log(`${status.padEnd(8)} ${item.name.padEnd(8)} ${item.output.split("\n")[0]}`);
+    }
+    const advices = buildDoctorAdvice(checks, options);
+    if (advices.length > 0) {
+        console.log("\nTargeted Advice:");
+        for (const advice of advices) {
+            const tag = advice.status === "ok" ? "OK" : "WARN";
+            console.log(`- ${tag} ${advice.label}: ${advice.detail}`);
+        }
+    }
+    if (failed > 0) {
+        console.log(`\ndoctor finished with ${failed} missing tools`);
+    }
+    else {
+        console.log("\ndoctor finished: all required tools found");
+    }
+}

package/dist/commands/list.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runList = runList;
+const config_1 = require("../types/config");
+const validator_1 = require("../core/validator");
+function join(items) {
+    return items.join(", ");
+}
+async function runList() {
+    console.log("PolyForge Scaffold Options");
+    console.log("");
+    console.log(`frontend: ${join(config_1.FRONTENDS)}`);
+    console.log(`backend: ${join(config_1.BACKENDS)}`);
+    console.log(`modules: ${join(config_1.EXTRA_MODULES)}`);
+    console.log(`data: ${join(config_1.DATA_MODULES)}`);
+    console.log(`packageManager: ${join(config_1.PACKAGE_MANAGERS)}`);
+    console.log("");
+    console.log("Defaults (--yes):");
+    console.log(`- frontend=${validator_1.DEFAULTS.frontend}`);
+    console.log(`- backend=${validator_1.DEFAULTS.backendMain}`);
+    console.log(`- modules=${validator_1.DEFAULTS.extraModules.join(",") || "none"}`);
+    console.log(`- data=${validator_1.DEFAULTS.dataModules.join(",")}`);
+    console.log(`- pm=${validator_1.DEFAULTS.packageManager}`);
+    console.log(`- install=${String(validator_1.DEFAULTS.installDeps)}`);
+    console.log(`- git=${String(validator_1.DEFAULTS.initGit)}`);
+    console.log(`- docker=${String(validator_1.DEFAULTS.docker)}`);
+    console.log("");
+    console.log("Rules:");
+    console.log("- data=none is mutually exclusive with other data modules");
+    console.log("- data modules can be combined (example: mysql,redis)");
+    console.log("- backend main stack is limited to go-gin and springboot");
+}

package/dist/core/git.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeInitGit = maybeInitGit;
+const child_process_1 = require("child_process");
+function run(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(cmd, args, { cwd, stdio: "ignore" });
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${cmd} ${args.join(" ")} failed with code ${code}`));
+        });
+    });
+}
+async function maybeInitGit(config) {
+    if (!config.initGit)
+        return;
+    try {
+        await run("git", ["init"], config.targetDir);
+    }
+    catch {
+        console.warn("[scaffold] skip git init (git unavailable)");
+    }
+}

package/dist/core/installer.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeInstallDeps = maybeInstallDeps;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("fs");
+function run(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(cmd, args, { cwd, stdio: "inherit", shell: process.platform === "win32" });
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${cmd} ${args.join(" ")} failed with code ${code}`));
+        });
+    });
+}
+async function maybeInstallDeps(config) {
+    if (!config.installDeps)
+        return;
+    if (config.frontend !== "none") {
+        const webDir = path_1.default.join(config.targetDir, "apps", "web");
+        if ((0, fs_1.existsSync)(path_1.default.join(webDir, "package.json"))) {
+            await run(config.packageManager, ["install"], webDir);
+        }
+    }
+    if (config.extraModules.includes("python-worker")) {
+        const pyDir = path_1.default.join(config.targetDir, "apps", "worker-python");
+        if ((0, fs_1.existsSync)(path_1.default.join(pyDir, "requirements.txt"))) {
+            try {
+                await run("python3", ["-m", "pip", "install", "-r", "requirements.txt"], pyDir);
+            }
+            catch {
+                console.warn("[scaffold] skip python dependency install (python3/pip unavailable)");
+            }
+        }
+    }
+    if (config.extraModules.includes("gateway-bff")) {
+        const bffDir = path_1.default.join(config.targetDir, "apps", "gateway-bff");
+        if ((0, fs_1.existsSync)(path_1.default.join(bffDir, "package.json"))) {
+            await run(config.packageManager, ["install"], bffDir);
+        }
+    }
+    if (config.extraModules.includes("auth-center")) {
+        const authDir = path_1.default.join(config.targetDir, "apps", "auth-center");
+        if ((0, fs_1.existsSync)(path_1.default.join(authDir, "package.json"))) {
+            await run(config.packageManager, ["install"], authDir);
+        }
+    }
+    if (config.extraModules.includes("python-ai")) {
+        const pyAiDir = path_1.default.join(config.targetDir, "apps", "python-ai");
+        if ((0, fs_1.existsSync)(path_1.default.join(pyAiDir, "requirements.txt"))) {
+            try {
+                await run("python3", ["-m", "pip", "install", "-r", "requirements.txt"], pyAiDir);
+            }
+            catch {
+                console.warn("[scaffold] skip python-ai dependency install (python3/pip unavailable)");
+            }
+        }
+    }
+}

package/dist/core/prompts.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCreateConfig = resolveCreateConfig;
+const path_1 = __importDefault(require("path"));
+const prompts_1 = __importDefault(require("prompts"));
+const config_1 = require("../types/config");
+const validator_1 = require("./validator");
+async function resolveCreateConfig(projectName, options) {
+    const targetDir = path_1.default.resolve(options.targetDir ?? process.cwd(), projectName);
+    const rawModuleInputs = (0, validator_1.parseCsv)(options.modules);
+    const rawDataInputs = (0, validator_1.parseCsv)(options.data);
+    const invalidModules = rawModuleInputs.filter((item) => !config_1.EXTRA_MODULES.includes(item));
+    const invalidDataModules = rawDataInputs.filter((item) => !config_1.DATA_MODULES.includes(item));
+    if (invalidModules.length > 0) {
+        throw new Error(`unsupported modules: ${invalidModules.join(", ")}`);
+    }
+    if (invalidDataModules.length > 0) {
+        throw new Error(`unsupported data modules: ${invalidDataModules.join(", ")}`);
+    }
+    const cliModules = (0, validator_1.parseExtraModules)(options.modules);
+    const cliDataModules = (0, validator_1.parseDataModules)(options.data);
+    const initial = {
+        projectName,
+        frontend: options.frontend,
+        backendMain: options.backend,
+        extraModules: cliModules.length > 0 ? cliModules : undefined,
+        dataModules: cliDataModules.length > 0 ? cliDataModules : undefined,
+        packageManager: options.pm,
+        installDeps: options.install,
+        initGit: options.git,
+        docker: options.docker,
+        targetDir,
+    };
+    let prompted = {};
+    if (!options.yes) {
+        prompted = await askMissing(initial);
+    }
+    return {
+        projectName,
+        targetDir,
+        frontend: initial.frontend ?? prompted.frontend ?? validator_1.DEFAULTS.frontend,
+        backendMain: initial.backendMain ?? prompted.backendMain ?? validator_1.DEFAULTS.backendMain,
+        extraModules: initial.extraModules ?? prompted.extraModules ?? validator_1.DEFAULTS.extraModules,
+        dataModules: initial.dataModules ?? prompted.dataModules ?? validator_1.DEFAULTS.dataModules,
+        packageManager: initial.packageManager ?? prompted.packageManager ?? validator_1.DEFAULTS.packageManager,
+        installDeps: initial.installDeps ?? prompted.installDeps ?? validator_1.DEFAULTS.installDeps,
+        initGit: initial.initGit ?? prompted.initGit ?? validator_1.DEFAULTS.initGit,
+        docker: initial.docker ?? prompted.docker ?? validator_1.DEFAULTS.docker,
+    };
+}
+async function askMissing(initial) {
+    const res = await (0, prompts_1.default)([
+        {
+            type: initial.frontend ? null : "select",
+            name: "frontend",
+            message: "Select frontend",
+            choices: [
+                { title: "react", value: "react" },
+                { title: "vue", value: "vue" },
+                { title: "none", value: "none" },
+            ],
+            initial: 0,
+        },
+        {
+            type: initial.backendMain ? null : "select",
+            name: "backendMain",
+            message: "Select backend",
+            choices: [
+                { title: "go-gin", value: "go-gin" },
+                { title: "springboot", value: "springboot" },
+            ],
+            initial: 0,
+        },
+        {
+            type: initial.extraModules ? null : "multiselect",
+            name: "extraModules",
+            message: "Select extra modules",
+            choices: [
+                { title: "python-worker", value: "python-worker" },
+                { title: "worker-go", value: "worker-go" },
+                { title: "gateway-bff", value: "gateway-bff" },
+                { title: "python-ai", value: "python-ai" },
+                { title: "grpc-service", value: "grpc-service" },
+                { title: "mq", value: "mq" },
+                { title: "cache-redis", value: "cache-redis" },
+                { title: "observability", value: "observability" },
+                { title: "auth-center", value: "auth-center" },
+            ],
+            hint: "Space to select",
+            min: 0,
+        },
+        {
+            type: initial.dataModules ? null : "multiselect",
+            name: "dataModules",
+            message: "Select data modules",
+            choices: [
+                { title: "mysql", value: "mysql" },
+                { title: "postgresql", value: "postgresql" },
+                { title: "redis", value: "redis" },
+                { title: "sqlite", value: "sqlite" },
+                { title: "mongodb", value: "mongodb" },
+                { title: "none", value: "none" },
+            ],
+            min: 1,
+            hint: "none cannot combine with others",
+        },
+        {
+            type: initial.packageManager ? null : "select",
+            name: "packageManager",
+            message: "Select package manager",
+            choices: [
+                { title: "pnpm", value: "pnpm" },
+                { title: "npm", value: "npm" },
+                { title: "yarn", value: "yarn" },
+            ],
+            initial: 1,
+        },
+        {
+            type: initial.installDeps !== undefined ? null : "toggle",
+            name: "installDeps",
+            message: "Install dependencies now?",
+            initial: false,
+            active: "yes",
+            inactive: "no",
+        },
+        {
+            type: initial.initGit !== undefined ? null : "toggle",
+            name: "initGit",
+            message: "Initialize git?",
+            initial: false,
+            active: "yes",
+            inactive: "no",
+        },
+        {
+            type: initial.docker !== undefined ? null : "toggle",
+            name: "docker",
+            message: "Generate docker baseline config?",
+            initial: false,
+            active: "yes",
+            inactive: "no",
+        },
+    ]);
+    return res;
+}