@kyuujs/cli 0.1.0-alpha.0

package/dist/runner/dev-runner.js

@@ -0,0 +1,209 @@
+import { fork } from "node:child_process";
+import { existsSync, watch as fsWatch } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function getRunnerPathAndArgs() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const currentDir = dirname(currentFile);
+    const jsInSameDir = resolve(currentDir, "app-runner.js");
+    if (existsSync(jsInSameDir)) {
+        return { execPath: jsInSameDir, execArgs: ["--experimental-strip-types"] };
+    }
+    const jsInDist = resolve(currentDir, "..", "..", "dist", "runner", "app-runner.js");
+    if (existsSync(jsInDist)) {
+        return { execPath: jsInDist, execArgs: ["--experimental-strip-types"] };
+    }
+    const tsInSameDir = resolve(currentDir, "app-runner.ts");
+    if (existsSync(tsInSameDir)) {
+        return { execPath: tsInSameDir, execArgs: ["--experimental-strip-types"] };
+    }
+    return { execPath: jsInSameDir, execArgs: ["--experimental-strip-types"] };
+}
+export async function startDevServer(options) {
+    const writeOut = options.stdout ?? ((msg) => process.stdout.write(msg + "\n"));
+    const writeErr = options.stderr ?? ((msg) => process.stderr.write(msg + "\n"));
+    const shouldWatch = options.watch ?? true;
+    const projectRoot = resolve(options.projectRoot);
+    let currentChild = null;
+    let watchers = [];
+    let debounceTimer = null;
+    let currentUrl;
+    let currentPort;
+    let currentHost;
+    const { execPath, execArgs } = getRunnerPathAndArgs();
+    const stopChild = async () => {
+        if (!currentChild)
+            return;
+        const child = currentChild;
+        currentChild = null;
+        if (child.exitCode !== null || child.killed) {
+            return;
+        }
+        await new Promise((res) => {
+            const timer = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                    // Ignore kill error
+                }
+                res();
+            }, 2000);
+            child.once("exit", () => {
+                clearTimeout(timer);
+                res();
+            });
+            try {
+                if (child.connected) {
+                    child.send("shutdown");
+                }
+                else {
+                    child.kill("SIGINT");
+                }
+            }
+            catch {
+                child.kill("SIGINT");
+            }
+        });
+    };
+    const spawnChild = async () => {
+        await stopChild();
+        return new Promise((res) => {
+            const child = fork(execPath, [], {
+                execArgv: execArgs,
+                env: {
+                    ...process.env,
+                    KYUU_PROJECT_ROOT: projectRoot,
+                    NODE_ENV: "development",
+                },
+                stdio: ["inherit", "pipe", "pipe", "ipc"],
+            });
+            currentChild = child;
+            let handled = false;
+            child.stdout?.on("data", (chunk) => {
+                writeOut(chunk.toString("utf8").trimEnd());
+            });
+            child.stderr?.on("data", (chunk) => {
+                writeErr(chunk.toString("utf8").trimEnd());
+            });
+            child.on("message", (msg) => {
+                if (typeof msg === "object" && msg !== null && "type" in msg) {
+                    const payload = msg;
+                    if (payload.type === "started") {
+                        handled = true;
+                        currentPort = payload.port;
+                        currentHost = payload.host;
+                        currentUrl = payload.url;
+                        const banner = [
+                            "Kyuu",
+                            "",
+                            "✓ Configuration loaded",
+                            "✓ Routes loaded",
+                            "✓ Server started",
+                            "",
+                            `Local: ${payload.url}`,
+                        ].join("\n");
+                        writeOut(banner);
+                        res(true);
+                    }
+                    else if (payload.type === "error") {
+                        handled = true;
+                        writeErr(`Unable to start Kyuu server.\n\n${payload.error}`);
+                        res(false);
+                    }
+                }
+            });
+            child.on("exit", (code) => {
+                if (!handled) {
+                    handled = true;
+                    if (code !== 0) {
+                        writeErr(`Application process exited with code ${code}.`);
+                    }
+                    res(false);
+                }
+            });
+        });
+    };
+    const restart = async () => {
+        writeOut("\nFile change detected. Restarting application...");
+        const success = await spawnChild();
+        if (!success) {
+            writeErr("\n✗ Failed to restart Kyuu application.\nWaiting for changes...");
+        }
+    };
+    // Initial spawn
+    await spawnChild();
+    // Watcher setup
+    if (shouldWatch) {
+        const handleFileChange = (_eventType, filename) => {
+            if (filename) {
+                const lower = filename.toLowerCase();
+                if (lower.includes("node_modules") ||
+                    lower.includes(".git") ||
+                    lower.includes("dist") ||
+                    lower.includes("coverage")) {
+                    return;
+                }
+            }
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+            }
+            debounceTimer = setTimeout(() => {
+                void restart();
+            }, 150);
+        };
+        try {
+            // Watch project root for kyuu.config changes
+            const rootWatcher = fsWatch(projectRoot, { recursive: false }, handleFileChange);
+            watchers.push(rootWatcher);
+            // Watch src directory for app route changes
+            const srcDir = join(projectRoot, "src");
+            if (existsSync(srcDir)) {
+                const srcWatcher = fsWatch(srcDir, { recursive: true }, handleFileChange);
+                watchers.push(srcWatcher);
+            }
+        }
+        catch {
+            // Fallback if watching fails
+        }
+    }
+    const cleanupAll = async () => {
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        for (const w of watchers) {
+            try {
+                w.close();
+            }
+            catch {
+                // Ignore close error
+            }
+        }
+        watchers = [];
+        await stopChild();
+    };
+    // Signal handlers
+    const sigintHandler = () => {
+        void cleanupAll().then(() => process.exit(0));
+    };
+    process.once("SIGINT", sigintHandler);
+    process.once("SIGTERM", sigintHandler);
+    return {
+        get url() {
+            return currentUrl;
+        },
+        get port() {
+            return currentPort;
+        },
+        get host() {
+            return currentHost;
+        },
+        stop: async () => {
+            process.removeListener("SIGINT", sigintHandler);
+            process.removeListener("SIGTERM", sigintHandler);
+            await cleanupAll();
+        },
+        restart,
+    };
+}
+//# sourceMappingURL=dev-runner.js.map

package/dist/runner/dev-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-runner.js","sourceRoot":"","sources":["../../src/runner/dev-runner.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns the authoritative version string from package.json.
+ */
+export declare function getVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CASnC"}

package/dist/version.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+/**
+ * Returns the authoritative version string from package.json.
+ */
+export function getVersion() {
+    try {
+        const pkgUrl = new URL("../package.json", import.meta.url);
+        const pkgContent = readFileSync(pkgUrl, "utf8");
+        const pkg = JSON.parse(pkgContent);
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3D,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAyB,CAAC;QAC3D,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@kyuujs/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "CLI tooling for Kyuu applications",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "kyuu": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@kyuujs/core": "0.1.0-alpha.0"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runCli } from "./dispatcher.js";
+
+runCli(process.argv.slice(2))
+  .then(({ exitCode }) => {
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  })
+  .catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });

package/src/commands/build.ts

@@ -0,0 +1,59 @@
+import { resolve } from "node:path";
+import { BUILD_OUTPUT_DIR, BuildOrchestrator, type BuildResult } from "@kyuujs/core";
+import type { BaseCliOptions, CliResult } from "../dispatcher.js";
+
+export interface BuildCommandOptions extends BaseCliOptions {
+  /** Target project root directory */
+  projectRoot?: string;
+  /** Working directory override */
+  cwd?: string;
+}
+
+export interface BuildCommandResult extends CliResult {
+  buildResult?: BuildResult;
+}
+
+/**
+ * Handles the "kyuu build" command execution pipeline.
+ */
+export async function handleBuildCommand(
+  args: string[] = [],
+  options: BuildCommandOptions = {},
+): Promise<BuildCommandResult> {
+  void args;
+  const writeOut = options.stdout ?? ((msg: string) => process.stdout.write(msg + "\n"));
+  const writeErr = options.stderr ?? ((msg: string) => process.stderr.write(msg + "\n"));
+
+  const rawRoot = options.projectRoot ?? options.cwd ?? process.cwd();
+  const projectRoot = resolve(rawRoot);
+
+  try {
+    const orchestrator = new BuildOrchestrator({ projectRoot });
+    const buildResult = await orchestrator.build();
+
+    const outputLines = [
+      "Kyuu build complete.",
+      "",
+      `  Build output: ${BUILD_OUTPUT_DIR}`,
+      `  Language:     ${buildResult.language}`,
+      `  Routes:       ${buildResult.manifest.routes.length}`,
+    ];
+
+    const message = outputLines.join("\n");
+    writeOut(message);
+
+    return {
+      exitCode: 0,
+      output: message,
+      buildResult,
+    };
+  } catch (err: unknown) {
+    const errMessage = err instanceof Error ? err.message : String(err);
+    const errText = `Kyuu build failed.\n\n${errMessage}`;
+    writeErr(errText);
+    return {
+      exitCode: 1,
+      output: errText,
+    };
+  }
+}

package/src/commands/dev.ts

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findConfigFile } from "@kyuujs/core";
+import type { BaseCliOptions, CliResult } from "../dispatcher.js";
+import { startDevServer, type DevServerController } from "../runner/dev-runner.js";
+
+export interface DevCommandOptions extends BaseCliOptions {
+  projectRoot?: string;
+  cwd?: string;
+  watch?: boolean;
+}
+
+export interface DevCommandResult extends CliResult {
+  controller?: DevServerController;
+}
+
+/**
+ * Handles the "kyuu dev" command execution pipeline.
+ */
+export async function handleDevCommand(
+  args: string[] = [],
+  options: DevCommandOptions = {},
+): Promise<DevCommandResult> {
+  void args;
+  const writeOut = options.stdout ?? ((msg: string) => process.stdout.write(msg + "\n"));
+  const writeErr = options.stderr ?? ((msg: string) => process.stderr.write(msg + "\n"));
+
+  const rawRoot = options.projectRoot ?? options.cwd ?? process.cwd();
+  const projectRoot = resolve(rawRoot);
+
+  const configFile = findConfigFile(projectRoot);
+  const hasPkgJson = existsSync(join(projectRoot, "package.json"));
+
+  if (!configFile && !hasPkgJson) {
+    const errText = [
+      "Kyuu project not found.",
+      "",
+      "Could not locate kyuu.config.ts from:",
+      `  ${projectRoot}`,
+      "",
+      'Run "kyuu new <name>" to create a new project.',
+    ].join("\n");
+    writeErr(errText);
+    return { exitCode: 3, output: errText };
+  }
+
+  let controller: DevServerController;
+  try {
+    controller = await startDevServer({
+      projectRoot,
+      watch: options.watch ?? true,
+      stdout: writeOut,
+      stderr: writeErr,
+    });
+  } catch (err: unknown) {
+    const errText = `Failed to start development server: ${err instanceof Error ? err.message : String(err)}`;
+    writeErr(errText);
+    return { exitCode: 4, output: errText };
+  }
+
+  if (!controller.url) {
+    await controller.stop();
+    const errText = "Failed to start development server.";
+    return { exitCode: 4, output: errText };
+  }
+
+  if (options.watch === false) {
+    await controller.stop();
+    return { exitCode: 0, output: "Development server started and stopped cleanly.", controller };
+  }
+
+  return { exitCode: 0, output: `Development server running at ${controller.url}`, controller };
+}

package/src/commands/new.ts

@@ -0,0 +1,107 @@
+import type { BaseCliOptions, CliResult } from "../dispatcher.js";
+import { initializeGitRepo } from "../project/git.js";
+import { installDependencies } from "../project/package-manager.js";
+import { scaffoldProject } from "../project/scaffolder.js";
+import { validateProjectName } from "../project/validation.js";
+import { CancelledError, runWizard } from "../project/wizard.js";
+import type { ProjectCreationOptions } from "../project/options.js";
+
+export interface NewCommandOptions extends BaseCliOptions {
+  cwd?: string;
+  defaults?: Partial<ProjectCreationOptions>;
+  interactive?: boolean;
+}
+
+/**
+ * Handles the "kyuu new <name>" command execution pipeline.
+ */
+export async function handleNewCommand(
+  args: string[] = [],
+  options: NewCommandOptions = {},
+): Promise<CliResult> {
+  const writeOut = options.stdout ?? ((msg: string) => process.stdout.write(msg + "\n"));
+  const writeErr = options.stderr ?? ((msg: string) => process.stderr.write(msg + "\n"));
+
+  const rawName = args[0];
+
+  if (!rawName || rawName.trim().length === 0) {
+    const errText = "Error: Missing project name.\nUsage: kyuu new <name>";
+    writeErr(errText);
+    return { exitCode: 1, output: errText };
+  }
+
+  const validation = validateProjectName(rawName, options.cwd);
+  if (!validation.valid || !validation.targetDirectory) {
+    const errText = `Error: ${validation.error}`;
+    writeErr(errText);
+    return { exitCode: 3, output: errText };
+  }
+
+  let creationOptions: ProjectCreationOptions;
+  try {
+    creationOptions = await runWizard({
+      name: rawName.trim(),
+      directory: validation.targetDirectory,
+      defaults: options.defaults,
+      interactive: options.interactive,
+    });
+  } catch (err) {
+    if (err instanceof CancelledError) {
+      const cancelText = "Operation cancelled. No project was created.";
+      writeOut(cancelText);
+      return { exitCode: 0, output: cancelText };
+    }
+    const errText = `Error: ${err instanceof Error ? err.message : String(err)}`;
+    writeErr(errText);
+    return { exitCode: 1, output: errText };
+  }
+
+  // 1. Scaffold files
+  try {
+    await scaffoldProject(creationOptions);
+  } catch (err: unknown) {
+    const errText = `Scaffolding failed: ${err instanceof Error ? err.message : String(err)}`;
+    writeErr(errText);
+    return { exitCode: 1, output: errText };
+  }
+
+  let installSuccess = true;
+  // 2. Install dependencies (unless skipInstall is true)
+  if (!creationOptions.skipInstall) {
+    const installResult = await installDependencies(
+      creationOptions.directory,
+      creationOptions.packageManager,
+    );
+    if (!installResult.success) {
+      installSuccess = false;
+      writeErr(`Warning: Dependency installation failed.\n${installResult.error}`);
+    }
+  }
+
+  // 3. Initialize Git if requested
+  if (creationOptions.initializeGit) {
+    const gitResult = await initializeGitRepo(creationOptions.directory);
+    if (!gitResult.success) {
+      writeErr("Warning: Git initialization failed. You can initialize Git manually.");
+    }
+  }
+
+  // 4. Report final success and next steps
+  const successLines = [
+    `✔ Kyuu project "${creationOptions.name}" created successfully.`,
+    "",
+    "Next steps:",
+    `  cd ${creationOptions.name}`,
+  ];
+
+  if (creationOptions.skipInstall || !installSuccess) {
+    successLines.push(`  ${creationOptions.packageManager} install`);
+  }
+
+  successLines.push(`  ${creationOptions.packageManager} run dev`);
+
+  const successText = successLines.join("\n");
+  writeOut(successText);
+
+  return { exitCode: 0, output: successText };
+}

package/src/commands/start.ts

@@ -0,0 +1,91 @@
+import { resolve } from "node:path";
+import { BUILD_OUTPUT_DIR, startProductionServer, type ProductionRunnerResult } from "@kyuujs/core";
+import type { BaseCliOptions, CliResult } from "../dispatcher.js";
+
+export interface StartCommandOptions extends BaseCliOptions {
+  /** Target project root directory */
+  projectRoot?: string;
+  /** Working directory override */
+  cwd?: string;
+  /** Port override for production HTTP server */
+  port?: number;
+  /** Host override for production HTTP server */
+  host?: string;
+  /** If true, attaches SIGINT/SIGTERM process signal handlers for graceful shutdown */
+  attachSignalHandlers?: boolean;
+}
+
+export interface StartCommandResult extends CliResult {
+  runnerResult?: ProductionRunnerResult;
+}
+
+/**
+ * Handles the "kyuu start" command execution pipeline.
+ */
+export async function handleStartCommand(
+  args: string[] = [],
+  options: StartCommandOptions = {},
+): Promise<StartCommandResult> {
+  void args;
+  const writeOut = options.stdout ?? ((msg: string) => process.stdout.write(msg + "\n"));
+  const writeErr = options.stderr ?? ((msg: string) => process.stderr.write(msg + "\n"));
+
+  const rawRoot = options.projectRoot ?? options.cwd ?? process.cwd();
+  const projectRoot = resolve(rawRoot);
+
+  try {
+    const runnerResult = await startProductionServer({
+      projectRoot,
+      port: options.port,
+      host: options.host,
+    });
+
+    const host = runnerResult.config.server.host;
+    const port = runnerResult.config.server.port;
+    const displayHost = host === "0.0.0.0" ? "localhost" : host;
+    const serverUrl = `http://${displayHost}:${port}`;
+
+    const outputLines = [
+      `Kyuu production server running at ${serverUrl}`,
+      "",
+      `  Build output: ${BUILD_OUTPUT_DIR}`,
+      `  Language:     ${runnerResult.manifest.metadata.language}`,
+      `  Routes:       ${runnerResult.manifest.routes.length}`,
+    ];
+
+    const message = outputLines.join("\n");
+    writeOut(message);
+
+    if (options.attachSignalHandlers !== false) {
+      const shutdown = async () => {
+        try {
+          await runnerResult.app.close();
+          writeOut("Kyuu server shut down gracefully.");
+        } catch {
+          // ignore shutdown errors on exit
+        }
+      };
+
+      process.once("SIGINT", () => {
+        void shutdown();
+      });
+      process.once("SIGTERM", () => {
+        void shutdown();
+      });
+    }
+
+    return {
+      exitCode: 0,
+      output: message,
+      runnerResult,
+    };
+  } catch (err: unknown) {
+    const errMessage = err instanceof Error ? err.message : String(err);
+    const errText = `Kyuu production server failed to start.\n\n${errMessage}`;
+    writeErr(errText);
+    return {
+      exitCode: 1,
+      output: errText,
+    };
+  }
+}