@yunsoft/yuncms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunsoft Software
+
+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,11 @@
+# @yunsoft/yuncms
+
+Command-line setup and runtime launcher for YunCMS.
+
+```bash
+npm install @yunsoft/yuncms
+npx yuncms init
+npx yuncms start
+```
+
+YunCMS requires Node.js 24 LTS and MySQL for V1. See the [project repository](https://github.com/Yunsoft-Software/yuncms) for setup, deployment and API documentation.

package/bin/yuncms.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { loadEnvFileIfPresent } from '@yunsoft/yuncms-core';
+import { runCli } from '../src/cli.js';
+
+loadEnvFileIfPresent();
+
+runCli().catch((error) => {
+  console.error(`YunCMS CLI failed${error?.code ? ` [${error.code}]` : ''}: ${error?.message ?? error}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@yunsoft/yuncms",
+  "version": "0.1.0",
+  "description": "Command-line setup and runtime launcher for YunCMS.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "bin": {
+    "yuncms": "./bin/yuncms.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yunsoft-Software/yuncms.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Yunsoft-Software/yuncms#readme",
+  "bugs": {
+    "url": "https://github.com/Yunsoft-Software/yuncms/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@yunsoft/yuncms-api": "0.1.0",
+    "@yunsoft/yuncms-core": "0.1.0"
+  }
+}

package/src/bootstrap-command.js

@@ -0,0 +1,32 @@
+import {
+  bootstrapDatabase,
+  closeDatabasePool,
+  createDatabasePool,
+  loadConfig,
+  pingDatabase,
+} from '@yunsoft/yuncms-core';
+
+export async function runBootstrapCommand({ env = process.env, output = console } = {}) {
+  const config = loadConfig(env);
+  const pool = createDatabasePool(config.database);
+
+  try {
+    const connected = await pingDatabase(pool);
+    if (!connected) {
+      const error = new Error('MySQL connection check returned an unexpected result');
+      error.code = 'DATABASE_UNAVAILABLE';
+      throw error;
+    }
+
+    const result = await bootstrapDatabase(pool);
+    output.log?.(
+      result.newlyApplied.length > 0
+        ? `YunCMS bootstrap applied: ${result.newlyApplied.join(', ')}`
+        : 'YunCMS database is already bootstrapped',
+    );
+    output.log?.(`Schema version: ${result.schemaVersion}`);
+    return result;
+  } finally {
+    await closeDatabasePool(pool);
+  }
+}

package/src/cli.js

@@ -0,0 +1,54 @@
+import { runBootstrapCommand } from './bootstrap-command.js';
+import { runInitCommand } from './init-command.js';
+import { runStartCommand } from './start-command.js';
+
+function assertSupportedNode(version = process.versions.node) {
+  const major = Number(String(version).split('.')[0]);
+  if (major !== 24) {
+    const error = new Error(`YunCMS requires Node.js 24 LTS; current runtime is ${version}`);
+    error.code = 'UNSUPPORTED_NODE_VERSION';
+    throw error;
+  }
+}
+
+function printHelp(output) {
+  output.log?.(`YunCMS CLI\n\nCommands:\n  yuncms init        Configure MySQL, bootstrap schema and create the first administrator\n  yuncms bootstrap   Apply required core database migrations\n  yuncms start       Start the YunCMS API using the current project environment\n  yuncms help        Show this help`);
+}
+
+export async function runCli(argv = process.argv.slice(2), {
+  output = console,
+  env = process.env,
+  cwd = process.cwd(),
+  prompts,
+  startCommand = runStartCommand,
+} = {}) {
+  assertSupportedNode();
+  const [command = 'help', ...rest] = argv;
+
+  if (rest.length > 0) {
+    const error = new Error(`Unexpected arguments for ${command}: ${rest.join(' ')}`);
+    error.code = 'INVALID_CLI_ARGUMENTS';
+    throw error;
+  }
+
+  switch (command) {
+    case 'init':
+      return runInitCommand({ env, cwd, output, ...(prompts ? { prompts } : {}) });
+    case 'bootstrap':
+      return runBootstrapCommand({ env, output });
+    case 'start':
+      return startCommand({ env, cwd, output });
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp(output);
+      return null;
+    default: {
+      const error = new Error(`Unknown YunCMS command: ${command}`);
+      error.code = 'UNKNOWN_CLI_COMMAND';
+      throw error;
+    }
+  }
+}
+
+export { assertSupportedNode };

package/src/env-file.js

@@ -0,0 +1,25 @@
+import { writeFile } from 'node:fs/promises';
+
+function encodeEnvValue(value) {
+  const text = String(value ?? '');
+  if (text.includes('\n') || text.includes('\r') || text.includes('\0')) {
+    const error = new Error('Environment values cannot contain newlines or null bytes');
+    error.code = 'INVALID_ENV_VALUE';
+    throw error;
+  }
+  return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+export function serializeEnv(values) {
+  return `${Object.entries(values)
+    .map(([key, value]) => `${key}=${encodeEnvValue(value)}`)
+    .join('\n')}\n`;
+}
+
+export async function writeEnvFile(path, values) {
+  await writeFile(path, serializeEnv(values), {
+    encoding: 'utf8',
+    mode: 0o600,
+    flag: 'wx',
+  });
+}

package/src/init-command.js

@@ -0,0 +1,112 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  bootstrapDatabase,
+  closeDatabasePool,
+  createDatabasePool,
+  createInitialAdmin,
+  findExistingAdmin,
+  loadConfig,
+  pingDatabase,
+} from '@yunsoft/yuncms-core';
+
+import { writeEnvFile } from './env-file.js';
+import { createInteractivePrompts } from './prompts.js';
+
+async function collectEnvironment(prompts) {
+  const DB_HOST = await prompts.line('MySQL host', { defaultValue: '127.0.0.1' });
+  const DB_PORT = await prompts.line('MySQL port', { defaultValue: '3306' });
+  const DB_DATABASE = await prompts.line('MySQL database', { defaultValue: 'yuncms' });
+  const DB_USER = await prompts.line('MySQL user', { defaultValue: 'yuncms' });
+  const DB_PASSWORD = await prompts.secret('MySQL password');
+  const DB_SSL = await prompts.line('Use MySQL TLS (true/false)', { defaultValue: 'false' });
+
+  return {
+    HOST: '127.0.0.1',
+    PORT: '8055',
+    STUDIO_ORIGIN: 'http://localhost:5173',
+    DB_HOST,
+    DB_PORT,
+    DB_DATABASE,
+    DB_USER,
+    DB_PASSWORD,
+    DB_CONNECTION_LIMIT: '10',
+    DB_SSL,
+  };
+}
+
+async function collectAdmin(prompts) {
+  const email = await prompts.line('Administrator email');
+  const password = await prompts.secret('Administrator password');
+  const confirmation = await prompts.secret('Confirm administrator password');
+
+  if (password !== confirmation) {
+    const error = new Error('Administrator passwords do not match');
+    error.code = 'PASSWORD_CONFIRMATION_MISMATCH';
+    throw error;
+  }
+
+  return { email, password };
+}
+
+export async function runInitCommand({
+  env = process.env,
+  cwd = process.cwd(),
+  output = console,
+  prompts = createInteractivePrompts(),
+} = {}) {
+  const envPath = join(cwd, '.env');
+  const workingEnv = { ...env };
+
+  if (!existsSync(envPath)) {
+    output.log?.('YunCMS setup: database configuration');
+    const collected = await collectEnvironment(prompts);
+    const config = loadConfig(collected);
+    void config;
+    await writeEnvFile(envPath, collected);
+    Object.assign(workingEnv, collected);
+    output.log?.(`Created ${envPath}`);
+  } else {
+    output.log?.(`Using existing ${envPath}`);
+  }
+
+  const config = loadConfig(workingEnv);
+  const pool = createDatabasePool(config.database);
+
+  try {
+    const connected = await pingDatabase(pool);
+    if (!connected) {
+      const error = new Error('MySQL connection check returned an unexpected result');
+      error.code = 'DATABASE_UNAVAILABLE';
+      throw error;
+    }
+    output.log?.('MySQL connection verified');
+
+    const bootstrap = await bootstrapDatabase(pool);
+    output.log?.(
+      bootstrap.newlyApplied.length > 0
+        ? `Applied migrations: ${bootstrap.newlyApplied.join(', ')}`
+        : 'Database migrations are already current',
+    );
+
+    const existingAdmin = await findExistingAdmin(pool);
+    if (existingAdmin) {
+      output.log?.(`Administrator already exists: ${existingAdmin.email}`);
+      output.log?.(`YunCMS API: http://${config.server.host}:${config.server.port}`);
+      output.log?.(`YunCMS Studio: ${config.server.studioOrigin}`);
+      return { bootstrap, admin: existingAdmin, existingAdmin: true };
+    }
+
+    output.log?.('YunCMS setup: first administrator');
+    const adminInput = await collectAdmin(prompts);
+    const admin = await createInitialAdmin(pool, adminInput);
+    output.log?.(`Created administrator: ${admin.email}`);
+    output.log?.(`YunCMS API: http://${config.server.host}:${config.server.port}`);
+    output.log?.(`YunCMS Studio: ${config.server.studioOrigin}`);
+
+    return { bootstrap, admin, existingAdmin: false };
+  } finally {
+    await closeDatabasePool(pool);
+  }
+}

package/src/prompts.js

@@ -0,0 +1,99 @@
+import { createInterface } from 'node:readline/promises';
+
+export async function promptLine(message, {
+  defaultValue = null,
+  input = process.stdin,
+  output = process.stdout,
+} = {}) {
+  const suffix = defaultValue == null ? ': ' : ` [${defaultValue}]: `;
+  const readline = createInterface({ input, output });
+
+  try {
+    const answer = await readline.question(`${message}${suffix}`);
+    const trimmed = answer.trim();
+    return trimmed === '' && defaultValue != null ? String(defaultValue) : trimmed;
+  } finally {
+    readline.close();
+  }
+}
+
+export async function promptSecret(message, {
+  input = process.stdin,
+  output = process.stdout,
+} = {}) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== 'function') {
+    const error = new Error('Secret prompts require an interactive TTY');
+    error.code = 'INTERACTIVE_TTY_REQUIRED';
+    throw error;
+  }
+
+  output.write(`${message}: `);
+  const previousRaw = input.isRaw === true;
+  const wasPaused = typeof input.isPaused === 'function' ? input.isPaused() : false;
+  const previousEncoding = input.readableEncoding ?? null;
+
+  return new Promise((resolve, reject) => {
+    let value = '';
+    let finished = false;
+
+    function onError(error) {
+      finish(error);
+    }
+
+    function cleanup() {
+      input.off('data', onData);
+      input.off('error', onError);
+      input.setRawMode(previousRaw);
+      if (previousEncoding) input.setEncoding(previousEncoding);
+      if (wasPaused) input.pause();
+    }
+
+    function finish(error = null) {
+      if (finished) return;
+      finished = true;
+      cleanup();
+      output.write('\n');
+      if (error) reject(error);
+      else resolve(value);
+    }
+
+    function onData(chunk) {
+      for (const character of String(chunk)) {
+        if (character === '\u0003') {
+          const error = new Error('Prompt cancelled');
+          error.code = 'PROMPT_CANCELLED';
+          finish(error);
+          return;
+        }
+        if (character === '\r' || character === '\n') {
+          finish();
+          return;
+        }
+        if (character === '\u007f' || character === '\b') {
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+            output.write('\b \b');
+          }
+          continue;
+        }
+        if (character >= ' ') {
+          value += character;
+          output.write('*');
+        }
+      }
+    }
+
+    input.setEncoding('utf8');
+    input.setRawMode(true);
+    input.resume();
+    input.on('data', onData);
+    input.once('error', onError);
+  });
+}
+
+export function createInteractivePrompts(options = {}) {
+  return {
+    line: (message, promptOptions = {}) => promptLine(message, { ...options, ...promptOptions }),
+    secret: (message, promptOptions = {}) => promptSecret(message, { ...options, ...promptOptions }),
+  };
+}

package/src/start-command.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export async function runStartCommand({
+  env = process.env,
+  cwd = process.cwd(),
+  output = console,
+  spawnProcess = spawn,
+  signalSource = process,
+} = {}) {
+  const serverUrl = import.meta.resolve('@yunsoft/yuncms-api/server');
+  const serverPath = fileURLToPath(serverUrl);
+
+  output.log?.(`Starting YunCMS API from ${cwd}`);
+
+  const child = spawnProcess(process.execPath, [serverPath], {
+    cwd,
+    env: { ...env },
+    stdio: 'inherit',
+    detached: process.platform !== 'win32',
+  });
+
+  return new Promise((resolve, reject) => {
+    let forwardedSignal = null;
+    const signalHandlers = new Map(
+      ['SIGINT', 'SIGTERM'].map((signal) => [signal, () => {
+        if (forwardedSignal || child.exitCode != null || child.signalCode != null) return;
+        forwardedSignal = signal;
+        child.kill(signal);
+      }]),
+    );
+    const cleanup = () => {
+      for (const [signal, handler] of signalHandlers) signalSource.off(signal, handler);
+    };
+    for (const [signal, handler] of signalHandlers) signalSource.on(signal, handler);
+
+    child.once('error', (error) => {
+      cleanup();
+      error.code ||= 'API_START_FAILED';
+      reject(error);
+    });
+    child.once('exit', (code, signal) => {
+      cleanup();
+      if (code === 0 || (signal && signal === forwardedSignal)) {
+        resolve({ code: 0, signal });
+        return;
+      }
+      const error = new Error(
+        signal
+          ? `YunCMS API exited after signal ${signal}`
+          : `YunCMS API exited with code ${code}`,
+      );
+      error.code = 'API_EXITED';
+      error.exitCode = code;
+      error.signal = signal;
+      reject(error);
+    });
+  });
+}