@kyuujs/cli 0.1.0-alpha.0

package/src/dispatcher.ts

@@ -0,0 +1,79 @@
+import { handleBuildCommand, type BuildCommandOptions } from "./commands/build.js";
+import { handleDevCommand, type DevCommandOptions } from "./commands/dev.js";
+import { handleNewCommand, type NewCommandOptions } from "./commands/new.js";
+import { handleStartCommand, type StartCommandOptions } from "./commands/start.js";
+import { getHelpText } from "./help.js";
+import { getVersion } from "./version.js";
+
+export interface BaseCliOptions {
+  stdout?: (msg: string) => void;
+  stderr?: (msg: string) => void;
+}
+
+export interface RunCliOptions
+  extends
+    BaseCliOptions,
+    NewCommandOptions,
+    DevCommandOptions,
+    BuildCommandOptions,
+    StartCommandOptions {}
+
+export interface CliResult {
+  exitCode: number;
+  output: string;
+}
+
+/**
+ * Main command dispatcher for Kyuu CLI.
+ * Inspects args for flags and commands, delegating to appropriate handlers.
+ */
+export async function runCli(args: string[] = [], options: RunCliOptions = {}): 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 hasHelp = args.includes("--help") || args.includes("-h");
+  const hasVersion = args.includes("--version") || args.includes("-v");
+
+  // 1. Help flag or bare invocation
+  if (args.length === 0 || hasHelp) {
+    const text = getHelpText();
+    writeOut(text);
+    return { exitCode: 0, output: text };
+  }
+
+  // 2. Version flag
+  if (hasVersion) {
+    const version = getVersion();
+    writeOut(version);
+    return { exitCode: 0, output: version };
+  }
+
+  // 3. Command resolution
+  const firstArg = args[0];
+
+  if (firstArg === "dev") {
+    return handleDevCommand(args.slice(1), options);
+  }
+
+  if (firstArg === "build") {
+    return handleBuildCommand(args.slice(1), options);
+  }
+
+  if (firstArg === "start") {
+    return handleStartCommand(args.slice(1), options);
+  }
+
+  if (firstArg === "new") {
+    return handleNewCommand(args.slice(1), options);
+  }
+
+  if (firstArg.startsWith("-")) {
+    const errText = `Unknown option: ${firstArg}\n\nRun "kyuu --help" for available options.`;
+    writeErr(errText);
+    return { exitCode: 1, output: errText };
+  }
+
+  const errText = `Unknown command: ${firstArg}\n\nRun "kyuu --help" for available commands.`;
+  writeErr(errText);
+  return { exitCode: 1, output: errText };
+}

package/src/help.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the concise help text for the Kyuu CLI foundation.
+ */
+export function getHelpText(): string {
+  return [
+    "Kyuu CLI",
+    "",
+    "Usage:",
+    "  kyuu <command> [options]",
+    "",
+    "Commands:",
+    "  dev         Start development server with live reload",
+    "  build       Build production application artifact",
+    "  start       Start production application server",
+    "  new         Scaffold a new Kyuu project",
+    "",
+    "Options:",
+    "  -h, --help       Show help",
+    "  -v, --version    Show version",
+    "",
+    'Run "kyuu --help" for available commands.',
+  ].join("\n");
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+import type { Server } from "node:http";
+import { resolve } from "node:path";
+import {
+  loadApplicationContext,
+  type ApplicationContext,
+  type ResolvedKyuuConfig,
+} from "@kyuujs/core";
+
+export type { ResolvedKyuuConfig };
+
+export {
+  handleBuildCommand,
+  type BuildCommandOptions,
+  type BuildCommandResult,
+} from "./commands/build.js";
+export { handleDevCommand, type DevCommandOptions, type DevCommandResult } from "./commands/dev.js";
+export { handleNewCommand, type NewCommandOptions } from "./commands/new.js";
+export {
+  handleStartCommand,
+  type StartCommandOptions,
+  type StartCommandResult,
+} from "./commands/start.js";
+export { runCli, type BaseCliOptions, type CliResult, type RunCliOptions } from "./dispatcher.js";
+export { getHelpText } from "./help.js";
+export { initializeGitRepo, type GitInitResult } from "./project/git.js";
+export {
+  type PackageManager,
+  type ProjectCreationOptions,
+  type ProjectLanguage,
+} from "./project/options.js";
+export { installDependencies, type InstallResult } from "./project/package-manager.js";
+export { scaffoldProject } from "./project/scaffolder.js";
+export { validateProjectName, type ValidationResult } from "./project/validation.js";
+export { CancelledError, runWizard, type WizardOptions } from "./project/wizard.js";
+export {
+  startDevServer,
+  type DevServerController,
+  type DevServerOptions,
+} from "./runner/dev-runner.js";
+export { getVersion } from "./version.js";
+
+export interface CliOptions {
+  projectRoot?: string;
+  mode?: "development" | "production";
+}
+
+export interface CliStartResult {
+  context: ApplicationContext;
+  server: Server;
+  config: ResolvedKyuuConfig;
+}
+
+/**
+ * Common startup pipeline for Kyuu CLI commands.
+ * Establishes project root, delegates to loadApplicationContext for automatic config discovery,
+ * and starts the HTTP server on the resolved host and port.
+ */
+export async function runCliCommand(
+  mode: "development" | "production",
+  options?: CliOptions,
+): Promise<CliStartResult> {
+  const projectRoot = options?.projectRoot ? resolve(options.projectRoot) : process.cwd();
+
+  const context = await loadApplicationContext({
+    projectRoot,
+  });
+
+  const server = context.app.listen();
+
+  if (!server.listening) {
+    await new Promise<void>((res, rej) => {
+      server.once("listening", res);
+      server.once("error", rej);
+    });
+  }
+
+  return {
+    context,
+    server,
+    config: context.config,
+  };
+}
+
+export async function runDev(options?: CliOptions): Promise<CliStartResult> {
+  return runCliCommand("development", options);
+}
+
+export async function runStart(options?: CliOptions): Promise<CliStartResult> {
+  return runCliCommand("production", options);
+}

package/src/project/git.ts

@@ -0,0 +1,31 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface GitInitResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Initializes a Git repository in the target directory if requested.
+ */
+export async function initializeGitRepo(
+  directory: string,
+  execFn: typeof execFileAsync = execFileAsync,
+): Promise<GitInitResult> {
+  try {
+    await execFn("git", ["init"], {
+      cwd: directory,
+      shell: process.platform === "win32",
+    });
+    return { success: true };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      error: message,
+    };
+  }
+}

package/src/project/options.ts

@@ -0,0 +1,11 @@
+export type ProjectLanguage = "typescript" | "javascript";
+export type PackageManager = "pnpm" | "npm" | "yarn";
+
+export interface ProjectCreationOptions {
+  name: string;
+  directory: string;
+  language: ProjectLanguage;
+  packageManager: PackageManager;
+  initializeGit: boolean;
+  skipInstall?: boolean;
+}

package/src/project/package-manager.ts

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { PackageManager } from "./options.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface InstallResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Installs project dependencies using the selected package manager.
+ */
+export async function installDependencies(
+  directory: string,
+  pm: PackageManager,
+  execFn: typeof execFileAsync = execFileAsync,
+): Promise<InstallResult> {
+  try {
+    const cmd = pm;
+    const args = ["install"];
+
+    await execFn(cmd, args, {
+      cwd: directory,
+      shell: process.platform === "win32",
+    });
+
+    return { success: true };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      error: message,
+    };
+  }
+}

package/src/project/scaffolder.ts

@@ -0,0 +1,140 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ProjectCreationOptions } from "./options.js";
+import { getVersion } from "../version.js";
+
+/**
+ * Scaffolds project files and directory structure based on ProjectCreationOptions.
+ */
+export async function scaffoldProject(options: ProjectCreationOptions): Promise<void> {
+  const version = getVersion();
+  const kyuuDepVersion = `^${version}`;
+
+  mkdirSync(options.directory, { recursive: true });
+
+  if (options.language === "typescript") {
+    // 1. kyuu.config.ts
+    writeFile(
+      join(options.directory, "kyuu.config.ts"),
+      `import { defineConfig } from "@kyuujs/core";
+
+export default defineConfig({
+  server: {
+    port: 3000,
+    host: "127.0.0.1",
+  },
+});
+`,
+    );
+
+    // 2. package.json
+    const pkgContent = {
+      name: options.name,
+      version: "0.1.0",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "kyuu dev",
+        build: "kyuu build",
+        start: "kyuu start",
+      },
+      dependencies: {
+        "@kyuujs/core": kyuuDepVersion,
+      },
+      devDependencies: {
+        "@kyuujs/cli": kyuuDepVersion,
+        typescript: "^5.0.0",
+      },
+    };
+    writeFile(join(options.directory, "package.json"), JSON.stringify(pkgContent, null, 2) + "\n");
+
+    // 3. tsconfig.json
+    const tsconfigContent = {
+      compilerOptions: {
+        target: "ES2022",
+        module: "NodeNext",
+        moduleResolution: "NodeNext",
+        esModuleInterop: true,
+        strict: true,
+        skipLibCheck: true,
+        outDir: "dist",
+      },
+      include: ["src/**/*", "kyuu.config.ts"],
+    };
+    writeFile(
+      join(options.directory, "tsconfig.json"),
+      JSON.stringify(tsconfigContent, null, 2) + "\n",
+    );
+
+    // 4. src/app/route.ts
+    writeFile(
+      join(options.directory, "src", "app", "route.ts"),
+      `import type { Request, Response } from "@kyuujs/core";
+
+export const GET = async (_req: Request, res: Response) => {
+  return res.json({ message: "Hello from Kyuu!" });
+};
+`,
+    );
+  } else {
+    // JavaScript project scaffolding
+    // 1. kyuu.config.js
+    writeFile(
+      join(options.directory, "kyuu.config.js"),
+      `import { defineConfig } from "@kyuujs/core";
+
+export default defineConfig({
+  server: {
+    port: 3000,
+    host: "127.0.0.1",
+  },
+});
+`,
+    );
+
+    // 2. package.json
+    const pkgContent = {
+      name: options.name,
+      version: "0.1.0",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "kyuu dev",
+        start: "kyuu start",
+      },
+      dependencies: {
+        "@kyuujs/core": kyuuDepVersion,
+      },
+      devDependencies: {
+        "@kyuujs/cli": kyuuDepVersion,
+      },
+    };
+    writeFile(join(options.directory, "package.json"), JSON.stringify(pkgContent, null, 2) + "\n");
+
+    // 3. src/app/route.js
+    writeFile(
+      join(options.directory, "src", "app", "route.js"),
+      `export const GET = async (_req, res) => {
+  return res.json({ message: "Hello from Kyuu!" });
+};
+`,
+    );
+  }
+
+  // Common files
+  // .gitignore
+  writeFile(
+    join(options.directory, ".gitignore"),
+    `node_modules/
+dist/
+.kyuu/
+.env
+*.log
+`,
+  );
+}
+
+function writeFile(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}

package/src/project/validation.ts

@@ -0,0 +1,67 @@
+import { existsSync, readdirSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  targetDirectory?: string;
+}
+
+/**
+ * Validates project name and resolves the target directory.
+ */
+export function validateProjectName(name: string, cwd: string = process.cwd()): ValidationResult {
+  if (!name || name.trim().length === 0) {
+    return { valid: false, error: "Project name cannot be empty." };
+  }
+
+  const trimmed = name.trim();
+
+  // Prevent path traversal and relative navigation in project name
+  if (
+    trimmed.includes("/") ||
+    trimmed.includes("\\") ||
+    trimmed.includes("..") ||
+    isAbsolute(trimmed)
+  ) {
+    return {
+      valid: false,
+      error: `Invalid project name "${trimmed}". Path traversal and absolute paths are not allowed.`,
+    };
+  }
+
+  // Prevent invalid npm package / directory name characters
+  const validNameRegex = /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
+  if (!validNameRegex.test(trimmed)) {
+    return {
+      valid: false,
+      error: `Invalid project name "${trimmed}". Must be a valid package/directory name.`,
+    };
+  }
+
+  const targetDirectory = resolve(cwd, trimmed);
+
+  if (existsSync(targetDirectory)) {
+    try {
+      const files = readdirSync(targetDirectory);
+      if (files.length > 0) {
+        return {
+          valid: false,
+          error: `Target directory already exists and is non-empty: ${targetDirectory}`,
+          targetDirectory,
+        };
+      }
+    } catch {
+      return {
+        valid: false,
+        error: `Target directory cannot be read: ${targetDirectory}`,
+        targetDirectory,
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    targetDirectory,
+  };
+}

package/src/project/wizard.ts

@@ -0,0 +1,89 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import type { PackageManager, ProjectCreationOptions, ProjectLanguage } from "./options.js";
+
+export interface WizardOptions {
+  name: string;
+  directory: string;
+  defaults?: Partial<ProjectCreationOptions>;
+  interactive?: boolean;
+  input?: NodeJS.ReadableStream;
+  output?: NodeJS.WritableStream;
+}
+
+export class CancelledError extends Error {
+  constructor() {
+    super("Project creation cancelled by user.");
+    this.name = "CancelledError";
+  }
+}
+
+/**
+ * Runs the interactive project creation wizard to resolve ProjectCreationOptions.
+ */
+export async function runWizard(options: WizardOptions): Promise<ProjectCreationOptions> {
+  const isInteractive = options.interactive ?? Boolean(process.stdout.isTTY && !process.env.CI);
+
+  // If non-interactive, return options immediately using defaults
+  if (!isInteractive) {
+    return {
+      name: options.name,
+      directory: options.directory,
+      language: options.defaults?.language ?? "typescript",
+      packageManager: options.defaults?.packageManager ?? "pnpm",
+      initializeGit: options.defaults?.initializeGit ?? true,
+      skipInstall: options.defaults?.skipInstall ?? false,
+    };
+  }
+
+  const rl = createInterface({
+    input: options.input ?? input,
+    output: options.output ?? output,
+  });
+
+  let cancelled = false;
+  rl.on("SIGINT", () => {
+    cancelled = true;
+    rl.close();
+  });
+
+  try {
+    // Question 1: Language
+    const langAnswer = await rl.question(
+      "\nWhich language would you like to use?\n  1) TypeScript (default)\n  2) JavaScript\nSelect [1-2]: ",
+    );
+    if (cancelled) throw new CancelledError();
+    const language: ProjectLanguage = langAnswer.trim() === "2" ? "javascript" : "typescript";
+
+    // Question 2: Package Manager
+    const pmAnswer = await rl.question(
+      "\nWhich package manager would you like to use?\n  1) pnpm (default)\n  2) npm\n  3) yarn\nSelect [1-3]: ",
+    );
+    if (cancelled) throw new CancelledError();
+    let packageManager: PackageManager = "pnpm";
+    if (pmAnswer.trim() === "2") packageManager = "npm";
+    if (pmAnswer.trim() === "3") packageManager = "yarn";
+
+    // Question 3: Git
+    const gitAnswer = await rl.question("\nInitialize a Git repository? [Y/n]: ");
+    if (cancelled) throw new CancelledError();
+    const initializeGit = !gitAnswer.trim().toLowerCase().startsWith("n");
+
+    rl.close();
+
+    return {
+      name: options.name,
+      directory: options.directory,
+      language,
+      packageManager,
+      initializeGit,
+      skipInstall: options.defaults?.skipInstall ?? false,
+    };
+  } catch (err) {
+    rl.close();
+    if (cancelled || (err instanceof Error && err.name === "AbortError")) {
+      throw new CancelledError();
+    }
+    throw err;
+  }
+}

package/src/runner/app-runner.ts

@@ -0,0 +1,61 @@
+import { loadApplicationContext } from "@kyuujs/core";
+
+async function run(): Promise<void> {
+  const projectRoot =
+    process.env.KYUU_PROJECT_ROOT ?? process.env.KYUU_PROJECT_ROOT ?? process.cwd();
+
+  try {
+    const context = await loadApplicationContext({ projectRoot });
+    const server = context.app.listen();
+
+    if (!server.listening) {
+      await new Promise<void>((res, rej) => {
+        server.once("listening", res);
+        server.once("error", rej);
+      });
+    }
+
+    const address = server.address();
+    let port = context.config.server.port;
+    let host = context.config.server.host;
+    if (address && typeof address === "object") {
+      port = address.port;
+      host = address.address;
+    }
+
+    const url = `http://${host === "0.0.0.0" || host === "127.0.0.1" ? "localhost" : host}:${port}`;
+
+    if (process.send) {
+      process.send({ type: "started", port, host, url });
+    }
+
+    const cleanup = async () => {
+      try {
+        await context.app.close();
+      } catch {
+        // Ignore shutdown errors
+      }
+      process.exit(0);
+    };
+
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("message", (msg) => {
+      if (msg === "shutdown") {
+        cleanup();
+      }
+    });
+  } catch (err: unknown) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    if (process.send) {
+      process.send({
+        type: "error",
+        error: errorMsg,
+        stack: err instanceof Error ? err.stack : undefined,
+      });
+    }
+    process.exit(1);
+  }
+}
+
+run();