@opentiny/tiny-robot-cli 0.4.1-alpha.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 - present OpenTiny Authors.
+Copyright (c) 2025 - present Huawei Cloud Computing Technologies Co., Ltd.
+
+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,21 @@
+# @opentiny/tiny-robot-cli
+
+A lightweight CLI for scaffolding TinyRobot-based product projects.
+
+## Usage
+
+```bash
+npx @opentiny/tiny-robot-cli create my-app
+pnpm dlx @opentiny/tiny-robot-cli create my-app
+```
+
+## Options
+
+- `-t, --template <name>`: template name, currently supports `basic`
+- `-h, --help`: show help
+
+## Template Documentation
+
+Template-specific features and environment variables are documented in each template directory, for example:
+
+- `packages/cli/templates/basic/README.md`

package/bin/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import { Command } from 'commander'
+
+import { registerCreateCommand } from './commands/create.js'
+import { registerAddCommand } from './commands/add.js'
+
+function run() {
+  const program = new Command()
+
+  program.name('tiny-robot-cli').description('CLI to scaffold TinyRobot product projects').showHelpAfterError()
+
+  registerCreateCommand(program)
+
+  registerAddCommand(program)
+
+  if (process.argv.length <= 2) {
+    program.outputHelp()
+    return
+  }
+
+  program.parse(process.argv)
+}
+
+run()

package/bin/commands/add.js

@@ -0,0 +1,436 @@
+import { checkbox, select } from '@inquirer/prompts'
+import { Argument } from 'commander'
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import semver from 'semver'
+
+import {
+  copyFile,
+  findProjectRoot,
+  findSubPackageRoot,
+  findWorkspacePackages,
+  findWorkspaceRoot,
+  getTemplateDir,
+  invariant,
+  listPackages,
+  logSkip,
+  logSuccess,
+  mergeEnvFile,
+} from '../utils.js'
+
+const DEP_NAME = '@opentiny/tiny-robot'
+const TARGET_VERSION = '0.4.2-alpha.5'
+const STYLE_IMPORT = "import '@opentiny/tiny-robot/dist/style.css'"
+
+function logUnavailable(label) {
+  logSkip(`${label} could not be applied`)
+}
+
+function logSkippedSelection(label) {
+  logSkip(`${label} change was not selected`)
+}
+
+async function resolveTargetPackage(cwd) {
+  const workspaceRoot = findWorkspaceRoot(cwd)
+
+  if (workspaceRoot) {
+    const subPackageRoot = findSubPackageRoot(cwd, workspaceRoot)
+
+    if (subPackageRoot) {
+      return subPackageRoot
+    }
+
+    const workspacePatterns = findWorkspacePackages(workspaceRoot)
+
+    const packageDirs = listPackages(workspaceRoot, workspacePatterns)
+
+    invariant(packageDirs.length > 0, 'no packages found in workspace.')
+
+    return select({
+      message: 'Multi-package workspace detected, select a target package:',
+      choices: packageDirs.map((dir) => ({
+        name: path.basename(dir),
+        value: dir,
+      })),
+    })
+  }
+
+  const projectRoot = findProjectRoot(cwd)
+
+  if (projectRoot) {
+    return projectRoot
+  }
+
+  console.error('Error: no package.json found.')
+
+  process.exit(1)
+}
+
+function getTemplateFile(...segments) {
+  return path.join(getTemplateDir('chat'), ...segments)
+}
+
+function readPackageJson(pkgPath) {
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+}
+
+function writePackageJson(pkgPath, pkg) {
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+}
+
+function findMainEntry(targetDir) {
+  for (const file of ['src/main.ts', 'src/main.js']) {
+    const fullPath = path.join(targetDir, file)
+
+    if (fs.existsSync(fullPath)) {
+      return fullPath
+    }
+  }
+
+  return null
+}
+
+function ensureStyleImport(mainFile) {
+  const content = fs.readFileSync(mainFile, 'utf-8')
+
+  if (content.includes(STYLE_IMPORT)) {
+    return {
+      type: 'skipped',
+    }
+  }
+
+  const lines = content.split('\n')
+
+  let lastImportIndex = -1
+
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*import\s/.test(lines[i])) {
+      lastImportIndex = i
+      continue
+    }
+
+    if (lastImportIndex !== -1) {
+      break
+    }
+  }
+
+  if (lastImportIndex === -1) {
+    lines.unshift(STYLE_IMPORT)
+  } else {
+    lines.splice(lastImportIndex + 1, 0, STYLE_IMPORT)
+  }
+
+  fs.writeFileSync(mainFile, lines.join('\n'))
+
+  return {
+    type: 'inserted',
+  }
+}
+
+function insertDependencyOrdered(dependencies, name, version) {
+  const next = {}
+
+  let inserted = false
+
+  for (const [key, value] of Object.entries(dependencies)) {
+    if (!inserted && name < key) {
+      next[name] = version
+      inserted = true
+    }
+
+    next[key] = value
+  }
+
+  if (!inserted) {
+    next[name] = version
+  }
+
+  return next
+}
+
+function ensureDependency(pkg, name, targetVersion) {
+  pkg.dependencies ??= {}
+
+  const currentVersion = pkg.dependencies[name]
+
+  if (!currentVersion) {
+    pkg.dependencies = insertDependencyOrdered(pkg.dependencies, name, targetVersion)
+
+    return {
+      type: 'added',
+    }
+  }
+
+  const validVersion = semver.minVersion(currentVersion)
+
+  if (validVersion && semver.lt(validVersion.version, targetVersion)) {
+    pkg.dependencies[name] = targetVersion
+
+    return {
+      type: 'updated',
+      from: currentVersion,
+      to: targetVersion,
+    }
+  }
+
+  return {
+    type: 'skipped',
+  }
+}
+
+function printDependencyResult(result, name) {
+  switch (result.type) {
+    case 'added':
+      logSuccess(`Added ${name}@${TARGET_VERSION}`)
+      break
+
+    case 'updated':
+      logSuccess(`Updated ${name} from ${result.from} to ${result.to}`)
+      break
+
+    case 'skipped':
+      logSkip(`${name} already satisfies required version`)
+      break
+  }
+}
+
+function getChatFeatureFiles(targetDir) {
+  const mainEntry = findMainEntry(targetDir)
+
+  return [
+    {
+      label: 'TinyRobotChat.vue',
+      target: path.join(targetDir, 'src/TinyRobotChat.vue'),
+      template: getTemplateFile('src', 'TinyRobotChat.vue'),
+      action(fileExists) {
+        return fileExists ? 'overwrite' : 'create'
+      },
+    },
+    {
+      label: 'main entry style import',
+      target: mainEntry,
+      action() {
+        return 'modify'
+      },
+    },
+    {
+      label: '.env',
+      target: path.join(targetDir, '.env'),
+      template: getTemplateFile('.env.example'),
+      action(fileExists) {
+        return fileExists ? 'modify' : 'create'
+      },
+    },
+
+    {
+      label: 'package.json',
+      target: path.join(targetDir, 'package.json'),
+      action() {
+        return 'modify'
+      },
+    },
+  ]
+}
+
+async function selectFileChanges(files) {
+  return checkbox({
+    message: 'Select which file changes to apply (all selected by default):',
+    choices: files.map((file) => {
+      const exists = file.target ? fs.existsSync(file.target) : false
+
+      const disabled = !file.target
+
+      const descriptions = {
+        'TinyRobotChat.vue': 'integrate TinyRobot chat component',
+        'main entry style import': 'import TinyRobot styles',
+        '.env': 'add environment variables',
+        'package.json': 'add TinyRobot dependencies',
+      }
+
+      const description = descriptions[file.label]
+
+      return {
+        name: disabled
+          ? `${file.action(false)} ${file.label} — ${description} (main.ts/js not found)`
+          : `${file.action(exists)} ${file.label} — ${description}`,
+
+        value: file.label,
+
+        checked: !disabled,
+
+        disabled,
+      }
+    }),
+  })
+}
+
+function isSelected(selectedFiles, label) {
+  return selectedFiles.includes(label)
+}
+
+async function addFeature(targetDir, type) {
+  invariant(type === 'chat', `unsupported feature: ${type}`)
+
+  const files = getChatFeatureFiles(targetDir)
+
+  const selectedFiles = await selectFileChanges(files)
+
+  if (selectedFiles.length === 0) {
+    logSkip('No changes selected.')
+    return
+  }
+
+  const componentFile = files.find((f) => {
+    return f.label === 'TinyRobotChat.vue'
+  })
+
+  const envFile = files.find((f) => {
+    return f.label === '.env'
+  })
+
+  invariant(componentFile, 'TinyRobotChat.vue config missing.')
+
+  invariant(envFile, '.env config missing.')
+
+  console.log('\nChange Results\n')
+
+  let mainImportChanged = false
+  let envChanged = false
+  let dependencyChanged = false
+
+  if (isSelected(selectedFiles, 'TinyRobotChat.vue')) {
+    copyFile(componentFile.template, componentFile.target)
+    logSuccess(`Copied ${componentFile.label}`)
+  } else {
+    logSkippedSelection(componentFile.label)
+  }
+
+  const mainFile = files.find((f) => {
+    return f.label === 'main entry style import'
+  })
+
+  if (!mainFile?.target) {
+    logUnavailable('main entry style import (main.ts/js not found)')
+  } else {
+    if (isSelected(selectedFiles, mainFile.label)) {
+      const result = ensureStyleImport(mainFile.target)
+
+      switch (result.type) {
+        case 'inserted':
+          mainImportChanged = true
+
+          logSuccess('Inserted TinyRobot style import')
+          break
+
+        case 'skipped':
+          logSkip('TinyRobot style import already exists')
+          break
+      }
+    } else {
+      logSkippedSelection(mainFile.label)
+    }
+  }
+
+  if (isSelected(selectedFiles, '.env')) {
+    const envResult = mergeEnvFile(envFile.template, envFile.target)
+
+    switch (envResult.type) {
+      case 'created':
+        envChanged = true
+
+        logSuccess('Created .env')
+        break
+
+      case 'merged':
+        envChanged = true
+
+        logSuccess(`Added ${envResult.added} env variables`)
+        break
+
+      case 'skipped':
+        logSkip('.env already contains required variables')
+        break
+    }
+  } else {
+    logSkippedSelection('.env')
+  }
+
+  const pkgPath = path.join(targetDir, 'package.json')
+
+  invariant(fs.existsSync(pkgPath), 'package.json not found.')
+
+  const pkg = readPackageJson(pkgPath)
+
+  if (isSelected(selectedFiles, 'package.json')) {
+    const result = ensureDependency(pkg, DEP_NAME, TARGET_VERSION)
+
+    if (result.type !== 'skipped') {
+      dependencyChanged = true
+    }
+
+    writePackageJson(pkgPath, pkg)
+
+    printDependencyResult(result, DEP_NAME)
+  } else {
+    logSkippedSelection('package.json')
+  }
+
+  console.log(`\nSuccessfully added "${type}" feature to ${targetDir}`)
+
+  printNextSteps({
+    mainImportChanged,
+    envChanged,
+    dependencyChanged,
+  })
+}
+
+function printNextSteps({ mainImportChanged, envChanged, dependencyChanged }) {
+  const steps = []
+
+  if (!mainImportChanged) {
+    steps.push(`Add "${STYLE_IMPORT}" to your application entry file.`)
+  }
+
+  steps.push('Render <TinyRobotChat /> near your main application component.')
+
+  if (envChanged) {
+    steps.push('Fill in your API key in .env.')
+  }
+
+  if (dependencyChanged) {
+    steps.push('Run npm/pnpm install to update dependencies.')
+  }
+
+  if (steps.length === 0) {
+    return
+  }
+
+  console.log('\nNext Steps\n')
+
+  for (const [index, step] of steps.entries()) {
+    console.log(`${index + 1}. ${step}`)
+  }
+}
+
+export function registerAddCommand(program) {
+  program
+    .command('add')
+    .description('Add a feature to the project')
+    .addArgument(new Argument('<type>', 'type of feature to add').choices(['chat']))
+    .action(async (type) => {
+      try {
+        const targetDir = await resolveTargetPackage(process.cwd())
+
+        await addFeature(targetDir, type)
+      } catch (error) {
+        if (error instanceof Error && error.name === 'ExitPromptError') {
+          console.error('\nOperation cancelled.')
+
+          process.exit(1)
+        }
+
+        throw error
+      }
+    })
+}

package/bin/commands/create.js

@@ -0,0 +1,144 @@
+import { input, select } from '@inquirer/prompts'
+import path from 'node:path'
+import process from 'node:process'
+
+import {
+  DEFAULT_PROJECT_NAME,
+  DEFAULT_TEMPLATE,
+  exists,
+  getAvailableTemplates,
+  getTemplateDir,
+  invariant,
+  scaffoldProject,
+  validateProjectName,
+} from '../utils.js'
+
+async function promptOrFallback(skipPrompt, fallbackValue, promptFactory) {
+  if (skipPrompt) {
+    return fallbackValue
+  }
+
+  return promptFactory()
+}
+
+async function resolveProjectName(initialValue, skipPrompt) {
+  if (initialValue) {
+    return initialValue
+  }
+
+  return promptOrFallback(skipPrompt, DEFAULT_PROJECT_NAME, () => {
+    return input({
+      message: 'Project name:',
+      default: DEFAULT_PROJECT_NAME,
+      validate(value) {
+        if (!value) {
+          return 'Project name is required.'
+        }
+
+        if (!validateProjectName(value)) {
+          return 'Project name can only contain lowercase letters, numbers, and dashes.'
+        }
+
+        const targetDir = path.resolve(process.cwd(), value)
+
+        if (exists(targetDir)) {
+          return `Target directory already exists: ${targetDir}`
+        }
+
+        return true
+      },
+    })
+  })
+}
+
+async function resolveTemplateName(initialValue, templates, skipPrompt) {
+  if (initialValue) {
+    return initialValue
+  }
+
+  const fallback = templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0]
+
+  return promptOrFallback(skipPrompt, fallback, () => {
+    return select({
+      message: 'Template:',
+      default: fallback,
+      choices: templates.map((templateName) => ({
+        name: templateName,
+        value: templateName,
+      })),
+    })
+  })
+}
+
+async function resolveCreateOptions(initialProjectName, initialTemplateName, skipPrompt) {
+  const availableTemplates = getAvailableTemplates()
+
+  invariant(availableTemplates.length > 0, 'no templates found.')
+
+  const projectName = await resolveProjectName(initialProjectName, skipPrompt)
+
+  const templateName = await resolveTemplateName(initialTemplateName, availableTemplates, skipPrompt)
+
+  return {
+    projectName,
+    templateName,
+    availableTemplates,
+  }
+}
+
+function validateCreateOptions(options) {
+  const { projectName, templateName, availableTemplates } = options
+
+  invariant(validateProjectName(projectName), 'project name can only contain lowercase letters, numbers, and dashes.')
+
+  const templateDir = getTemplateDir(templateName)
+
+  invariant(
+    exists(templateDir),
+    `template "${templateName}" does not exist. Available: ${availableTemplates.join(', ')}`,
+  )
+
+  const targetDir = path.resolve(process.cwd(), projectName)
+
+  invariant(!exists(targetDir), `target directory already exists: ${targetDir}`)
+
+  return {
+    templateDir,
+    targetDir,
+  }
+}
+
+function printCreateSuccess(projectName) {
+  console.log('\nProject created successfully!')
+  console.log('\nNext steps:')
+  console.log(`  cd ${projectName}`)
+  console.log('  pnpm install')
+  console.log('  pnpm dev')
+  console.log()
+}
+
+async function createProject(initialProjectName, initialTemplateName, skipPrompt) {
+  const options = await resolveCreateOptions(initialProjectName, initialTemplateName, skipPrompt)
+
+  const { templateDir, targetDir } = validateCreateOptions(options)
+
+  scaffoldProject(templateDir, targetDir, options.projectName)
+
+  printCreateSuccess(options.projectName)
+}
+
+export function registerCreateCommand(program) {
+  program
+    .command('create [project-name]')
+    .description('Create a TinyRobot project from template')
+    .option('-t, --template <name>', 'template name')
+    .action((projectName, options) => {
+      const skipPrompt = !process.stdout.isTTY
+
+      createProject(projectName ?? '', options.template ?? '', skipPrompt).catch((error) => {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`)
+
+        process.exit(1)
+      })
+    })
+}