@objectdocs/cli 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @objectdocs/cli
+
+## 0.2.1
+
+### Patch Changes
+
+- Bug fixes and improvements for ObjectDocs
+- Updated dependencies
+  - @objectdocs/site@0.2.1
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial release of ObjectDocs - A modern documentation engine built on Next.js 14 and Fumadocs
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectdocs/site@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of ObjectDocs
+
+  - Modern documentation engine built on Next.js 14 and Fumadocs
+  - Metadata-driven architecture with configuration as code
+  - Support for low-code component embedding
+  - Enterprise-grade UI with dark mode support
+  - Multi-product documentation support
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectdocs/site@0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @objectdocs/cli
+
+The central CLI orchestration tool for the ObjectStack documentation platform.
+
+## Overview
+
+This CLI acts as the unified interface for developing, building, and translating the ObjectStack documentation. It wraps the application logic in `@objectdocs/site` and adds workflow automation.
+
+## Features
+
+- **Site Orchestration**: Manages the Next.js development server and static build process.
+- **AI Translation**: Automatically translates MDX documentation from English to Chinese using OpenAI.
+- **Artifact Management**: Handles build output movement and directory structure organization.
+- **Smart Updates**: Can process specific files or bulk translate the entire documentation.
+
+## Installation
+
+This package is part of the monorepo workspace. Install dependencies from the root:
+
+```bash
+pnpm install
+```
+
+## Usage
+
+### Site Management
+
+The CLI can also be used to run the documentation site locally with a VitePress-like experience.
+
+```bash
+# Start Dev Server
+# Usage: pnpm objectdocs dev [docs-directory]
+pnpm objectdocs dev ./content/docs
+
+# Build Static Site
+# Usage: pnpm objectdocs build [docs-directory]
+pnpm objectdocs build ./content/docs
+```
+
+### Translate Documentation
+
+The `translate` command reads English documentation from `content/docs/*.mdx` and generates Chinese translations as `*.cn.mdx` files in the same directory using the dot parser convention.
+
+**Prerequisites:**
+You must set the following environment variables (in `.env` or your shell):
+
+```bash
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://api.openai.com/v1 # Optional
+```
+
+**Commands:**
+
+```bash
+# Translate a specific file
+pnpm objectdocs translate content/docs/00-intro/index.mdx
+
+# Translate multiple files
+pnpm objectdocs translate content/docs/00-intro/index.mdx content/docs/01-quickstart/index.mdx
+
+# Translate all files in content/docs
+pnpm objectdocs translate --all
+
+# Specify a custom model (default: gpt-4o)
+pnpm objectdocs translate --all --model gpt-4-turbo
+```
+
+### CI/CD Integration
+
+In CI environments, you can use the `CHANGED_FILES` environment variable to translate only modified files:
+
+```bash
+export CHANGED_FILES="content/docs/new-page.mdx"
+pnpm objectdocs translate
+```

package/bin/cli.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * ObjectDocs
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { cac } from 'cac';
+import 'dotenv/config';
+import { registerTranslateCommand } from '../src/commands/translate.mjs';
+import { registerDevCommand } from '../src/commands/dev.mjs';
+import { registerBuildCommand } from '../src/commands/build.mjs';
+import { registerStartCommand } from '../src/commands/start.mjs';
+
+const cli = cac('objectdocs');
+
+registerTranslateCommand(cli);
+registerDevCommand(cli);
+registerBuildCommand(cli);
+registerStartCommand(cli);
+
+cli.help();
+cli.version('0.0.1');
+
+cli.parse();
+

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@objectdocs/cli",
+  "version": "0.2.1",
+  "type": "module",
+  "bin": {
+    "objectdocs": "./bin/cli.mjs"
+  },
+  "dependencies": {
+    "@types/node": "^25.0.8",
+    "cac": "^6.7.14",
+    "dotenv": "^16.4.5",
+    "openai": "^4.0.0",
+    "typescript": "^5.9.3",
+    "@objectdocs/site": "0.2.1"
+  },
+  "scripts": {
+    "dev": "node ./bin/cli.mjs dev ../../content/docs",
+    "build": "node ./bin/cli.mjs build ../../content/docs",
+    "translate": "node ./bin/cli.mjs translate",
+    "test": "echo \"No test specified\" && exit 0"
+  }
+}

package/src/commands/build.mjs

@@ -0,0 +1,106 @@
+/**
+ * ObjectDocs
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+export function registerBuildCommand(cli) {
+  cli
+    .command('build [dir]', 'Build static documentation site')
+    .action(async (dir, options) => {
+      // 1. Resolve user's docs directory
+      const docsDir = dir ? path.resolve(process.cwd(), dir) : path.resolve(process.cwd(), 'content/docs');
+      
+      // 2. Resolve the Next.js App directory
+      let nextAppDir;
+      try {
+        nextAppDir = path.dirname(require.resolve('@objectdocs/site/package.json'));
+      } catch (e) {
+        // Fallback for local development
+         nextAppDir = path.resolve(__dirname, '../../../site');
+      }
+
+      // Copy user config and assets to nextAppDir
+      const userConfigPath = path.resolve(process.cwd(), 'content/docs.site.json');
+      if (fs.existsSync(userConfigPath)) {
+        console.log(`  Copying config from ${userConfigPath}`);
+        fs.cpSync(userConfigPath, path.join(nextAppDir, 'docs.site.json'));
+      }
+      
+      const userPublicPath = path.resolve(process.cwd(), 'public');
+      if (fs.existsSync(userPublicPath)) {
+        console.log(`  Copying public assets from ${userPublicPath}`);
+        const targetPublicDir = path.join(nextAppDir, 'public');
+        if (!fs.existsSync(targetPublicDir)) {
+          fs.mkdirSync(targetPublicDir, { recursive: true });
+        }
+        fs.cpSync(userPublicPath, targetPublicDir, { recursive: true, force: true });
+      }
+
+      console.log(`Building docs site...`);
+      console.log(`  Engine: ${nextAppDir}`);
+      console.log(`  Content: ${docsDir}`);
+      
+      const env = {
+        ...process.env,
+        DOCS_DIR: docsDir
+      };
+
+      const nextCmd = 'npm'; 
+      const args = ['run', 'build'];
+
+      const child = spawn(nextCmd, args, {
+        stdio: 'inherit',
+        env,
+        cwd: nextAppDir // CRITICAL: Run in the Next.js app directory
+      });
+
+      child.on('close', (code) => {
+        if (code === 0) {
+          // Copy output to project root
+          const src = path.join(nextAppDir, 'out');
+          const dest = path.join(process.cwd(), 'out');
+          
+          if (fs.existsSync(src)) {
+            console.log(`\nMoving build output to ${dest}...`);
+            if (fs.existsSync(dest)) {
+                fs.rmSync(dest, { recursive: true, force: true });
+            }
+            fs.cpSync(src, dest, { recursive: true });
+            console.log(`Build successfully output to: ${dest}`);
+          } else {
+            // Check for .next directory (dynamic build)
+            const srcNext = path.join(nextAppDir, '.next');
+            const destNext = path.join(process.cwd(), '.next');
+            
+            if (fs.existsSync(srcNext) && srcNext !== destNext) {
+               console.log(`\nLinking .next build output to ${destNext}...`);
+               if (fs.existsSync(destNext)) {
+                   fs.rmSync(destNext, { recursive: true, force: true });
+               }
+               // Use symlink instead of copy to preserve internal symlinks in .next (pnpm support)
+               fs.symlinkSync(srcNext, destNext, 'dir');
+               console.log(`Build successfully linked to: ${destNext}`);
+            } else {
+               console.log(`\nNo 'out' directory generated in ${src}.`);
+               console.log(`This is expected if 'output: export' is disabled.`);
+            }
+          }
+        }
+        process.exit(code);
+      });
+
+    });
+}

package/src/commands/dev.mjs

@@ -0,0 +1,105 @@
+/**
+ * ObjectDocs
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { spawn } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+export function registerDevCommand(cli) {
+  cli
+    .command('dev [dir]', 'Start development server')
+    .option('--port <port>', 'Port to listen on', { default: 7777 })
+    .action(async (dir, options) => {
+      // 1. Resolve user's docs directory (Absolute path)
+      const docsDir = dir ? path.resolve(process.cwd(), dir) : path.resolve(process.cwd(), 'content/docs');
+      
+      // 2. Resolve the Next.js App directory
+      let nextAppDir;
+      try {
+        nextAppDir = path.dirname(require.resolve('@objectdocs/site/package.json'));
+      } catch (e) {
+        // Fallback for local development
+         nextAppDir = path.resolve(__dirname, '../../../site');
+      }
+
+      console.log(`Starting docs server...`);
+      console.log(`  Engine: ${nextAppDir}`);
+      console.log(`  Content: ${docsDir}`);
+      
+      const env = {
+        ...process.env,
+        DOCS_DIR: docsDir,
+        PORT: options.port
+      };
+      
+      const nextCmd = 'npm'; 
+      const args = ['run', 'dev', '--', '-p', options.port];
+
+      let child;
+      let isRestarting = false;
+      let debounceTimer;
+
+      const startServer = () => {
+        // Sync config and assets before starting
+        const userConfigPath = path.resolve(process.cwd(), 'content/docs.site.json');
+        if (fs.existsSync(userConfigPath)) {
+          fs.cpSync(userConfigPath, path.join(nextAppDir, 'docs.site.json'));
+        }
+
+        const userPublicPath = path.resolve(process.cwd(), 'public');
+        if (fs.existsSync(userPublicPath)) {
+          const targetPublicDir = path.join(nextAppDir, 'public');
+          if (!fs.existsSync(targetPublicDir)) {
+            fs.mkdirSync(targetPublicDir, { recursive: true });
+          }
+          fs.cpSync(userPublicPath, targetPublicDir, { recursive: true, force: true });
+        }
+
+        child = spawn(nextCmd, args, {
+          stdio: 'inherit',
+          env,
+          cwd: nextAppDir // CRITICAL: Run in the Next.js app directory
+        });
+
+        child.on('close', (code) => {
+          if (isRestarting) {
+            isRestarting = false;
+            startServer();
+          } else {
+            // Only exit if we are not restarting. 
+            // Null code means killed by signal (like our kill() call), but we handle that via flag.
+            process.exit(code || 0);
+          }
+        });
+      };
+
+      startServer();
+
+      // Watch for config changes
+      const configFile = path.resolve(process.cwd(), 'content/docs.site.json');
+      if (fs.existsSync(configFile)) {
+        console.log(`Watching config: ${configFile}`);
+        fs.watch(configFile, (eventType) => {
+          if (eventType === 'change') {
+            clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+              console.log('\nConfig changed. Restarting server...');
+              isRestarting = true;
+              child.kill();
+            }, 500);
+          }
+        });
+      }
+    });
+}

package/src/commands/start.mjs

@@ -0,0 +1,77 @@
+/**
+ * ObjectDocs
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+export function registerStartCommand(cli) {
+  cli.command('start [dir]', 'Start the production server')
+    .action((dir) => {
+      // 1. Resolve Next.js App directory
+      let nextAppDir;
+      try {
+        nextAppDir = path.dirname(require.resolve('@objectdocs/site/package.json'));
+      } catch (e) {
+         nextAppDir = path.resolve(__dirname, '../../../site');
+      }
+
+      // 2. Check config
+      let isStatic = false;
+      try {
+        const configPath = path.resolve(process.cwd(), 'content/docs.site.json');
+        if (fs.existsSync(configPath)) {
+          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+          if (config.build?.output === 'export') {
+            isStatic = true;
+          }
+        }
+      } catch (e) {
+        // ignore
+      }
+
+      if (isStatic || (dir && dir !== 'out')) {
+        // Static Mode
+        const targetDir = dir ? path.resolve(process.cwd(), dir) : path.resolve(process.cwd(), 'out');
+        console.log(`Serving static site from: ${targetDir}`);
+        
+        const child = spawn('npx', ['serve', targetDir], {
+          stdio: 'inherit',
+          shell: true
+        });
+        
+        child.on('error', (err) => {
+          console.error('Failed to start server:', err);
+        });
+      } else {
+        // Dynamic Mode (Next.js start)
+        console.log('Starting Next.js production server...');
+        console.log(`  Engine: ${nextAppDir}`);
+        
+        const docsDir = path.resolve(process.cwd(), 'content/docs');
+
+        const env = {
+          ...process.env,
+          DOCS_DIR: docsDir
+        };
+
+
+        const child = spawn('npm', ['start'], {
+          cwd: nextAppDir,
+          stdio: 'inherit',
+          env: env
+        });
+      }
+    });
+}

package/src/commands/translate.mjs

@@ -0,0 +1,93 @@
+/**
+ * ObjectDocs
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import OpenAI from 'openai';
+import { getAllMdxFiles, resolveTranslatedFilePath, translateContent, getSiteConfig } from '../utils/translate.mjs';
+
+export function registerTranslateCommand(cli) {
+  cli
+    .command('translate [files...]', 'Translate documentation files')
+    .option('--all', 'Translate all files in content/docs')
+    .option('--model <model>', 'OpenAI model to use', { default: 'gpt-4o' })
+    .action(async (files, options) => {
+      const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+      const OPENAI_BASE_URL = process.env.OPENAI_BASE_URL;
+
+      if (!OPENAI_API_KEY) {
+        console.error('Error: Missing OPENAI_API_KEY environment variable.');
+        process.exit(1);
+      }
+
+      const openai = new OpenAI({
+        apiKey: OPENAI_API_KEY,
+        baseURL: OPENAI_BASE_URL,
+      });
+
+      // Get language configuration
+      const config = getSiteConfig();
+      console.log(`Translation target: ${config.defaultLanguage} -> ${config.targetLanguage}`);
+      console.log(`Configured languages: ${config.languages.join(', ')}\n`);
+
+      let targetFiles = [];
+
+      if (options.all) {
+        console.log('Scanning for all .mdx files in content/docs...');
+        targetFiles = getAllMdxFiles('content/docs');
+      } else if (files && files.length > 0) {
+          targetFiles = files;
+      } else if (process.env.CHANGED_FILES) {
+          targetFiles = process.env.CHANGED_FILES.split(',');
+      }
+
+      if (targetFiles.length === 0) {
+        console.log('No files to translate.');
+        console.log('Usage:');
+        console.log('  objectdocs translate content/docs/file.mdx');
+        console.log('  objectdocs translate --all');
+        console.log('  (CI): Set CHANGED_FILES environment variable');
+        return;
+      }
+
+      console.log(`Processing ${targetFiles.length} files...`);
+
+      for (const file of targetFiles) {
+          const enFilePath = path.resolve(process.cwd(), file);
+          
+          if (!fs.existsSync(enFilePath)) {
+              console.log(`File skipped (not found): ${file}`);
+              continue;
+          }
+
+          const zhFilePath = resolveTranslatedFilePath(enFilePath);
+          
+          if (zhFilePath === enFilePath) {
+              console.log(`Skipping: Source and destination are the same for ${file}`);
+              continue;
+          }
+
+          console.log(`Translating: ${file} -> ${path.relative(process.cwd(), zhFilePath)}`);
+
+          try {
+              const content = fs.readFileSync(enFilePath, 'utf-8');
+              const translatedContent = await translateContent(content, openai, options.model);
+
+              const dir = path.dirname(zhFilePath);
+              if (!fs.existsSync(dir)) {
+                  fs.mkdirSync(dir, { recursive: true });
+              }
+
+              fs.writeFileSync(zhFilePath, translatedContent);
+              console.log(`✓ Automatically translated: ${zhFilePath}`);
+          } catch (error) {
+              console.error(`✗ Failed to translate ${file}:`, error);
+          }
+      }
+    });
+}

package/src/utils/translate.mjs

@@ -0,0 +1,148 @@
+/**
+ * ObjectDocs
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import OpenAI from 'openai';
+
+/**
+ * Load site configuration from docs.site.json
+ * @returns {object} - The site configuration
+ */
+function loadSiteConfig() {
+  const configPath = path.resolve(process.cwd(), 'content/docs.site.json');
+  
+  if (!fs.existsSync(configPath)) {
+    console.warn(`Warning: docs.site.json not found at ${configPath}, using defaults`);
+    // Fallback matches the default configuration in packages/site/lib/site-config.ts
+    return {
+      i18n: {
+        enabled: true,
+        defaultLanguage: 'en',
+        languages: ['en', 'cn']
+      }
+    };
+  }
+  
+  try {
+    const configContent = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(configContent);
+  } catch (error) {
+    console.error('Error loading docs.site.json:', error);
+    throw error;
+  }
+}
+
+// Load configuration
+const siteConfig = loadSiteConfig();
+const languages = siteConfig.i18n?.languages || ['en', 'cn'];
+const defaultLanguage = siteConfig.i18n?.defaultLanguage || 'en';
+
+// Generate language suffixes dynamically from config
+// e.g., ['en', 'cn'] -> ['.en.mdx', '.cn.mdx']
+const LANGUAGE_SUFFIXES = languages.map(lang => `.${lang}.mdx`);
+
+// Target language is the first non-default language
+const targetLanguage = languages.find(lang => lang !== defaultLanguage) || languages[0];
+const TARGET_LANGUAGE_SUFFIX = `.${targetLanguage}.mdx`;
+
+/**
+ * Get the current site configuration
+ * @returns {object} - Configuration object with languages info
+ */
+export function getSiteConfig() {
+  return {
+    languages,
+    defaultLanguage,
+    targetLanguage,
+    languageSuffixes: LANGUAGE_SUFFIXES,
+    targetLanguageSuffix: TARGET_LANGUAGE_SUFFIX,
+  };
+}
+
+/**
+ * Check if a file has a language suffix
+ * @param {string} filePath - The file path to check
+ * @returns {boolean} - True if file has a language suffix
+ */
+function hasLanguageSuffix(filePath) {
+  return LANGUAGE_SUFFIXES.some(suffix => filePath.endsWith(suffix));
+}
+
+export function getAllMdxFiles(dir) {
+  let results = [];
+  if (!fs.existsSync(dir)) return results;
+  
+  const list = fs.readdirSync(dir);
+  list.forEach(file => {
+    file = path.join(dir, file);
+    const stat = fs.statSync(file);
+    if (stat && stat.isDirectory()) {
+      results = results.concat(getAllMdxFiles(file));
+    } else {
+      // Only include .mdx files that don't have language suffix
+      if (file.endsWith('.mdx') && !hasLanguageSuffix(file)) {
+        results.push(path.relative(process.cwd(), file));
+      }
+    }
+  });
+  return results;
+}
+
+export function resolveTranslatedFilePath(enFilePath) {
+  // Strategy: Use dot parser convention
+  // content/docs/path/to/file.mdx -> content/docs/path/to/file.{targetLang}.mdx
+  // Target language is determined from docs.site.json configuration
+  // Skip files that already have language suffix
+  const absPath = path.resolve(enFilePath);
+  
+  // Skip if already has a language suffix
+  if (hasLanguageSuffix(absPath)) {
+    return absPath;
+  }
+  
+  // Replace .mdx with target language suffix
+  if (absPath.endsWith('.mdx')) {
+    return absPath.replace(/\.mdx$/, TARGET_LANGUAGE_SUFFIX);
+  }
+  
+  return absPath;
+}
+
+export async function translateContent(content, openai, model) {
+  const prompt = `
+You are a technical documentation translator for "ObjectStack".
+Translate the following MDX documentation from English to Chinese (Simplified).
+
+Rules:
+1. Preserve all MDX frontmatter (keys and structure). only translate the values if they are regular text.
+2. Preserve all code blocks exactly as they are. Do not translate code comments unless they are purely explanatory and not part of the logic.
+3. Use professional software terminology (e.g. "ObjectStack", "ObjectQL", "ObjectUI" should strictly remain in English).
+4. "Local-First" translate to "本地优先".
+5. "Protocol-Driven" translate to "协议驱动".
+6. Maintain the original markdown formatting (links, bold, italics).
+
+Content to translate:
+---
+${content}
+---
+`;
+
+  try {
+    const response = await openai.chat.completions.create({
+      model: model,
+      messages: [{ role: 'user', content: prompt }],
+      temperature: 0.1,
+    });
+
+    return response.choices[0].message.content.trim();
+  } catch (error) {
+    console.error('Translation failed:', error);
+    throw error;
+  }
+}