@expressots/cli 3.0.0 → 4.0.0-preview.3

package/bin/providers/create/form.js

@@ -7,9 +7,44 @@ exports.createExternalProvider = void 0;
 const chalk_1 = __importDefault(require("chalk"));
 const degit_1 = __importDefault(require("degit"));
 const inquirer_1 = __importDefault(require("inquirer"));
+const cli_1 = require("../../cli");
 const center_text_1 = require("../../utils/center-text");
 const change_package_info_1 = require("../../utils/change-package-info");
 const cli_ui_1 = require("../../utils/cli-ui");
+/**
+ * Override the templates ref/tag, mirroring `EXPRESSOTS_TEMPLATE_REF` in the
+ * `new` command. Lets users target a branch (e.g. `feature/v4.0`) before the
+ * matching version tag has been pushed.
+ */
+const TEMPLATE_REF_OVERRIDE = process.env.EXPRESSOTS_TEMPLATE_REF?.trim() || "";
+const PREVIEW_FALLBACK_REF = "feature/v4.0";
+function isPreviewBuild() {
+    return /-(?:preview|alpha|beta|rc)\b/i.test(cli_1.BUNDLE_VERSION);
+}
+function resolveProviderRef() {
+    if (TEMPLATE_REF_OVERRIDE)
+        return TEMPLATE_REF_OVERRIDE;
+    return `v${cli_1.BUNDLE_VERSION}`;
+}
+async function cloneProviderTemplate(targetDir) {
+    const primaryRef = resolveProviderRef();
+    const primaryRepo = `expressots/templates/provider#${primaryRef}`;
+    try {
+        await (0, degit_1.default)(primaryRepo, { force: false }).clone(targetDir);
+        return;
+    }
+    catch (err) {
+        const isMissingRef = err?.code === "MISSING_REF";
+        const canFallback = isMissingRef && !TEMPLATE_REF_OVERRIDE && isPreviewBuild();
+        if (!canFallback)
+            throw err;
+        console.log(chalk_1.default.yellow(`\n⚠  Templates tag "${primaryRef}" not found on GitHub yet — falling back to "${PREVIEW_FALLBACK_REF}". ` +
+            `Set EXPRESSOTS_TEMPLATE_REF=<branch-or-tag> to override.`));
+        await (0, degit_1.default)(`expressots/templates/provider#${PREVIEW_FALLBACK_REF}`, {
+            force: false,
+        }).clone(targetDir);
+    }
+}
 async function printInfo(providerName) {
     console.log("\n");
     console.log("🐎 Provider", chalk_1.default.green(providerName), "created successfully!");
@@ -39,8 +74,15 @@ const createExternalProvider = async (provider) => {
             ]);
         }
         try {
-            const emitter = (0, degit_1.default)(`expressots/templates/provider`);
-            await emitter.clone(providerInfo.providerName);
+            // Pinned to the templates tag matching this CLI's published version,
+            // same policy as `expressots new`. BUNDLE_VERSION reads from the
+            // CLI's own package.json so the ref always tracks the release.
+            //
+            // Mirrors the preview-fallback logic in `new/form.ts`: during the
+            // preview window the matching `vX.Y.Z` tag may not yet be on
+            // `expressots/templates`, so we soft-fall back to the active
+            // release branch and warn rather than failing opaquely.
+            await cloneProviderTemplate(providerInfo.providerName);
             (0, change_package_info_1.changePackageName)({
                 directory: providerInfo.providerName,
                 name: providerInfo.providerName,
@@ -50,7 +92,15 @@ const createExternalProvider = async (provider) => {
         }
         catch (err) {
             console.log("\n");
-            (0, cli_ui_1.printError)("Project already exists or Folder is not empty", "");
+            const msg = err?.message ? String(err.message) : String(err);
+            const code = err?.code ? ` [${err.code}]` : "";
+            if (err?.code === "DEST_NOT_EMPTY" ||
+                /already exists|not empty/i.test(msg)) {
+                (0, cli_ui_1.printError)(`Target folder "${providerInfo.providerName}" already exists or is not empty`, "");
+            }
+            else {
+                (0, cli_ui_1.printError)(`Failed to scaffold provider${code}: ${msg}`, "");
+            }
             reject(err);
         }
     });

package/bin/scripts/form.js

@@ -4,19 +4,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scriptsForm = void 0;
-const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const path_1 = __importDefault(require("path"));
 const cli_ui_1 = require("../utils/cli-ui");
+const input_validation_1 = require("../utils/input-validation");
+const safe_spawn_1 = require("../utils/safe-spawn");
 const cwd = process.cwd();
 const packageJsonPath = path_1.default.join(cwd, "package.json");
 function readPackageJson() {
+    let raw;
     try {
-        return JSON.parse(fs_1.default.readFileSync(packageJsonPath, "utf8"));
+        raw = fs_1.default.readFileSync(packageJsonPath, "utf8");
     }
     catch (e) {
-        (0, cli_ui_1.printError)(`Error reading package.json`, "scripts-command");
+        (0, cli_ui_1.printError)(`Error reading package.json: ${e.message}`, "scripts-command");
+        process.exit(1);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        (0, cli_ui_1.printError)(`package.json is not valid JSON: ${e.message}`, "scripts-command");
         process.exit(1);
     }
 }
@@ -51,14 +60,27 @@ async function promptUserToSelectScripts(scripts) {
 }
 function executeScripts(scripts, selectedScripts, runner) {
     selectedScripts.forEach((script) => {
+        if (!(0, input_validation_1.isValidScriptName)(script)) {
+            (0, cli_ui_1.printWarning)(`Skipping script with invalid name: ${JSON.stringify(script)}`, "scripts-command");
+            return;
+        }
         console.log(`Running ${script}...`);
         try {
-            const command = `${runner} run ${script}`;
+            // `safeSpawnSync` (cross-spawn) handles Windows `.cmd` shim
+            // resolution and cmd.exe-aware argv escaping. Script names
+            // are also constrained to a strict alphanumeric/dash/dot
+            // charset by `isValidScriptName` above for defense in depth.
             const options = {
                 stdio: "inherit",
                 env: { ...process.env },
             };
-            (0, child_process_1.execSync)(command, options);
+            const result = (0, safe_spawn_1.safeSpawnSync)(runner, ["run", script], options);
+            if (result.error) {
+                throw result.error;
+            }
+            if (typeof result.status === "number" && result.status !== 0) {
+                throw new Error(`exited with code ${result.status}`);
+            }
         }
         catch (e) {
             (0, cli_ui_1.printWarning)(`Command ${script} cancelled or failed - ${e}`, "scripts-command");

package/bin/studio/cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Studio command CLI implementation
+ */
+import type { CommandModule } from "yargs";
+interface StudioYargsOptions {
+    port: number;
+    "agent-port": number;
+    "no-browser": boolean;
+    src: string;
+}
+/**
+ * Studio command definition
+ */
+export declare function studioCommand(): CommandModule<object, StudioYargsOptions>;
+export {};

package/bin/studio/cli.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Studio command CLI implementation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.studioCommand = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const cli_1 = require("../cli");
+const safe_spawn_1 = require("../utils/safe-spawn");
+/**
+ * Check if @expressots/studio is installed
+ */
+function isStudioInstalled() {
+    try {
+        // Check if the package exists in node_modules
+        const studioPath = (0, path_1.resolve)(process.cwd(), "node_modules/@expressots/studio");
+        return (0, fs_1.existsSync)(studioPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install @expressots/studio as a dev dependency
+ */
+async function installStudio() {
+    const spinner = (0, ora_1.default)("Installing @expressots/studio...").start();
+    try {
+        const hasYarn = (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), "yarn.lock"));
+        const hasPnpm = (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), "pnpm-lock.yaml"));
+        // Pin the studio install to the same minor as the running CLI so
+        // `expressots studio` from a preview-N CLI fetches a matching
+        // preview-N studio. Falls back to a caret on the major if the CLI
+        // version isn't a valid prerelease (defensive).
+        const studioSpec = `@expressots/studio@^${cli_1.BUNDLE_VERSION}`;
+        let pkgManager;
+        let args;
+        if (hasPnpm) {
+            pkgManager = "pnpm";
+            args = ["add", "-D", studioSpec];
+        }
+        else if (hasYarn) {
+            pkgManager = "yarn";
+            args = ["add", "-D", studioSpec];
+        }
+        else {
+            pkgManager = "npm";
+            args = ["install", "-D", studioSpec];
+        }
+        // `safeSpawnSync` (cross-spawn) resolves the Windows `.cmd` shim
+        // and properly escapes argv for cmd.exe. The argv here is a
+        // fixed list of literal strings, so it is safe by construction.
+        const result = (0, safe_spawn_1.safeSpawnSync)(pkgManager, args, {
+            stdio: "pipe",
+        });
+        if (result.error)
+            throw result.error;
+        if (typeof result.status === "number" && result.status !== 0) {
+            throw new Error(`exited with code ${result.status}`);
+        }
+        spinner.succeed(chalk_1.default.green("@expressots/studio installed successfully"));
+        return true;
+    }
+    catch (error) {
+        spinner.fail(chalk_1.default.red("Failed to install @expressots/studio"));
+        console.error(chalk_1.default.yellow("\nPlease install manually: npm install -D @expressots/studio"));
+        return false;
+    }
+}
+/**
+ * Launch the Studio
+ */
+async function launchStudio(options) {
+    const args = ["start"];
+    if (options.port) {
+        args.push("--port", String(options.port));
+    }
+    if (options.agentPort) {
+        args.push("--agent-port", String(options.agentPort));
+    }
+    if (options.noBrowser) {
+        args.push("--no-browser");
+    }
+    if (options.src) {
+        args.push("--src", options.src);
+    }
+    const isWindows = process.platform === "win32";
+    const studioBinName = isWindows
+        ? "expressots-studio.cmd"
+        : "expressots-studio";
+    const studioPath = (0, path_1.resolve)(process.cwd(), "node_modules/.bin", studioBinName);
+    // `safeSpawn` (cross-spawn) handles Windows `.cmd` shim invocation
+    // and per-arg cmd.exe escaping, so user-controlled flags like
+    // `--src` or `--port` cannot break out into shell metacharacters
+    // even if the project path itself contains spaces.
+    const child = (0, safe_spawn_1.safeSpawn)(studioPath, args, {
+        stdio: "inherit",
+        cwd: process.cwd(),
+    });
+    child.on("error", (error) => {
+        console.error(chalk_1.default.red("Failed to start Studio:"), error.message);
+        process.exit(1);
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+}
+/**
+ * Studio command handler
+ */
+async function studioHandler(options) {
+    // Check if Studio is installed
+    if (!isStudioInstalled()) {
+        console.log(chalk_1.default.yellow("📦 @expressots/studio is not installed in this project."));
+        console.log("");
+        // Try to install
+        const installed = await installStudio();
+        if (!installed) {
+            process.exit(1);
+        }
+        console.log("");
+    }
+    // Launch Studio
+    await launchStudio(options);
+}
+/**
+ * Studio command definition
+ */
+function studioCommand() {
+    return {
+        command: "studio",
+        describe: "Launch ExpressoTS Studio - Developer Experience Platform",
+        builder: (yargs) => yargs
+            .option("port", {
+            alias: "p",
+            type: "number",
+            default: 3333,
+            description: "UI port",
+        })
+            .option("agent-port", {
+            alias: "a",
+            type: "number",
+            default: 3334,
+            description: "Agent WebSocket port",
+        })
+            .option("no-browser", {
+            type: "boolean",
+            default: false,
+            description: "Do not open browser automatically",
+        })
+            .option("src", {
+            type: "string",
+            default: "./src",
+            description: "Source directory to scan",
+        }),
+        handler: async (argv) => {
+            await studioHandler({
+                port: argv.port,
+                agentPort: argv["agent-port"],
+                noBrowser: argv["no-browser"],
+                src: argv.src,
+            });
+        },
+    };
+}
+exports.studioCommand = studioCommand;

package/bin/studio/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ExpressoTS Studio CLI integration
+ * Launches the local Studio development environment
+ */
+export { studioCommand } from "./cli";

package/bin/studio/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * ExpressoTS Studio CLI integration
+ * Launches the local Studio development environment
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.studioCommand = void 0;
+var cli_1 = require("./cli");
+Object.defineProperty(exports, "studioCommand", { enumerable: true, get: function () { return cli_1.studioCommand; } });

package/bin/templates/cache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Template cache management
+ * Stores templates locally for offline access and performance
+ */
+import type { CacheConfig } from "./types";
+export declare class TemplateCache {
+    private config;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Ensure cache directory exists
+     */
+    private ensureCacheDir;
+    /**
+     * Generate cache key from template identifier
+     */
+    private getCacheKey;
+    /**
+     * Get cache file path
+     */
+    private getCachePath;
+    /**
+     * Check if cache entry is valid (not expired)
+     */
+    private isValid;
+    /**
+     * Get cached template content
+     */
+    get<T>(category: string, platform: string, variant?: string): T | null;
+    /**
+     * Set cached template content
+     */
+    set<T>(category: string, platform: string, data: T, variant?: string, ttl?: number): void;
+    /**
+     * Delete cached template
+     */
+    delete(category: string, platform: string, variant?: string): void;
+    /**
+     * Clear all cached templates
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        files: number;
+        totalSize: number;
+        oldestEntry: Date | null;
+    };
+    /**
+     * Get cache directory path
+     */
+    getCacheDirectory(): string;
+}
+export declare function getTemplateCache(config?: Partial<CacheConfig>): TemplateCache;

package/bin/templates/cache.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Template cache management
+ * Stores templates locally for offline access and performance
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTemplateCache = exports.TemplateCache = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const DEFAULT_CACHE_DIR = path_1.default.join(os_1.default.homedir(), ".expressots", "cache", "templates");
+const DEFAULT_TTL = 86400; // 24 hours in seconds
+class TemplateCache {
+    constructor(config) {
+        this.config = {
+            directory: config?.directory || DEFAULT_CACHE_DIR,
+            ttl: config?.ttl || DEFAULT_TTL,
+        };
+        this.ensureCacheDir();
+    }
+    /**
+     * Ensure cache directory exists
+     */
+    ensureCacheDir() {
+        if (!fs_1.default.existsSync(this.config.directory)) {
+            fs_1.default.mkdirSync(this.config.directory, { recursive: true });
+        }
+    }
+    /**
+     * Generate cache key from template identifier
+     */
+    getCacheKey(category, platform, variant) {
+        const parts = [category, platform];
+        if (variant)
+            parts.push(variant);
+        return parts.join("-") + ".cache.json";
+    }
+    /**
+     * Get cache file path
+     */
+    getCachePath(key) {
+        return path_1.default.join(this.config.directory, key);
+    }
+    /**
+     * Check if cache entry is valid (not expired)
+     */
+    isValid(entry) {
+        const now = Date.now();
+        const expiresAt = entry.timestamp + entry.ttl * 1000;
+        return now < expiresAt;
+    }
+    /**
+     * Get cached template content
+     */
+    get(category, platform, variant) {
+        const key = this.getCacheKey(category, platform, variant);
+        const cachePath = this.getCachePath(key);
+        try {
+            if (!fs_1.default.existsSync(cachePath)) {
+                return null;
+            }
+            const content = fs_1.default.readFileSync(cachePath, "utf-8");
+            const entry = JSON.parse(content);
+            if (!this.isValid(entry)) {
+                // Cache expired, remove it
+                this.delete(category, platform, variant);
+                return null;
+            }
+            return entry.data;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Set cached template content
+     */
+    set(category, platform, data, variant, ttl) {
+        const key = this.getCacheKey(category, platform, variant);
+        const cachePath = this.getCachePath(key);
+        const entry = {
+            data,
+            timestamp: Date.now(),
+            ttl: ttl || this.config.ttl,
+        };
+        try {
+            fs_1.default.writeFileSync(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+        }
+        catch (error) {
+            // Silently fail - cache is optional
+            console.error("Failed to write cache:", error);
+        }
+    }
+    /**
+     * Delete cached template
+     */
+    delete(category, platform, variant) {
+        const key = this.getCacheKey(category, platform, variant);
+        const cachePath = this.getCachePath(key);
+        try {
+            if (fs_1.default.existsSync(cachePath)) {
+                fs_1.default.unlinkSync(cachePath);
+            }
+        }
+        catch {
+            // Ignore deletion errors
+        }
+    }
+    /**
+     * Clear all cached templates
+     */
+    clear() {
+        try {
+            const files = fs_1.default.readdirSync(this.config.directory);
+            for (const file of files) {
+                if (file.endsWith(".cache.json")) {
+                    fs_1.default.unlinkSync(path_1.default.join(this.config.directory, file));
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        let files = 0;
+        let totalSize = 0;
+        let oldestTimestamp = Infinity;
+        try {
+            const entries = fs_1.default.readdirSync(this.config.directory);
+            for (const file of entries) {
+                if (!file.endsWith(".cache.json"))
+                    continue;
+                const filePath = path_1.default.join(this.config.directory, file);
+                const stat = fs_1.default.statSync(filePath);
+                files++;
+                totalSize += stat.size;
+                try {
+                    const content = JSON.parse(fs_1.default.readFileSync(filePath, "utf-8"));
+                    if (content.timestamp < oldestTimestamp) {
+                        oldestTimestamp = content.timestamp;
+                    }
+                }
+                catch {
+                    // Skip invalid cache files
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist or can't be read
+        }
+        return {
+            files,
+            totalSize,
+            oldestEntry: oldestTimestamp === Infinity ? null : new Date(oldestTimestamp),
+        };
+    }
+    /**
+     * Get cache directory path
+     */
+    getCacheDirectory() {
+        return this.config.directory;
+    }
+}
+exports.TemplateCache = TemplateCache;
+// Singleton instance
+let cacheInstance = null;
+function getTemplateCache(config) {
+    if (!cacheInstance) {
+        cacheInstance = new TemplateCache(config);
+    }
+    return cacheInstance;
+}
+exports.getTemplateCache = getTemplateCache;

package/bin/templates/cli.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Templates CLI command
+ * Manage template sources, cache, and configuration
+ */
+import { CommandModule } from "yargs";
+type CommandModuleArgs = Record<string, never>;
+declare const templatesCommand: () => CommandModule<CommandModuleArgs, any>;
+export { templatesCommand };