@myvillage/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyVillage Project
+
+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,195 @@
+# MyVillageOS CLI
+
+A command-line interface for MyVillage Project student developers to create, manage, and deploy educational games built with Three.js for the M-UNI platform.
+
+## Installation
+
+Requires Node.js 18 or higher.
+
+### From npm (once published)
+
+```bash
+npm install -g @myvillage/cli
+```
+
+> **Note:** The package is not yet published to npm. Use the development install below.
+
+### Development install (from source)
+
+```bash
+# Clone the repository
+git clone https://github.com/MyVillage-Project-Technologies/MyVillageOS-CLI.git
+cd MyVillageOS-CLI
+
+# Install dependencies
+npm install
+
+# Link the CLI globally so "myvillage" command works anywhere
+npm link
+```
+
+After linking, the `myvillage` command is available system-wide. To unlink later, run `npm unlink -g @myvillage/cli`.
+
+You can also run commands directly without linking:
+
+```bash
+node bin/myvillage.js --help
+node bin/myvillage.js create-game
+```
+
+## Quick Start
+
+```bash
+# 1. Log in with your MyVillageOS account
+myvillage login
+
+# 2. Create a new game project
+myvillage create-game
+
+# 3. Develop your game
+cd my-game
+npm run dev
+
+# 4. Deploy to MyVillageOS
+myvillage deploy
+```
+
+## Commands
+
+### `myvillage login`
+
+Authenticate with your MyVillageOS account via OAuth. Opens your browser for secure login, then stores credentials locally.
+
+```bash
+myvillage login
+```
+
+### `myvillage logout`
+
+Clear stored credentials.
+
+```bash
+myvillage logout
+```
+
+### `myvillage create-game`
+
+Interactive wizard to scaffold a new game project. Choose from four templates:
+
+| Template | Description |
+|----------|-------------|
+| **Quiz Game** | Test knowledge with interactive questions, scoring, and celebrations |
+| **Exploration Game** | Navigate with WASD, collect items, minimap, and inventory |
+| **Narrative Game** | Story-driven with dialogue, branching choices, and scene transitions |
+| **Custom** | Base Three.js template to build anything from scratch |
+
+All templates include:
+- Responsive Three.js canvas (desktop + mobile)
+- Camera and lighting setup
+- Input handling (keyboard, mouse, touch)
+- MyVillage brand styling
+- UI overlay system
+- Audio manager
+- Vite dev server with hot reload
+
+```bash
+myvillage create-game
+```
+
+### `myvillage deploy`
+
+Build and deploy your game to the MyVillageOS platform. Run this from inside a game project directory.
+
+```bash
+cd my-game
+myvillage deploy
+```
+
+You earn MVT tokens for each successful deployment.
+
+### `myvillage status`
+
+Check deployment status and analytics. If run inside a game project directory, shows status for that game. Otherwise, lists all your deployed games.
+
+```bash
+myvillage status
+```
+
+## Game Project Structure
+
+Games created with the CLI follow this structure:
+
+```
+my-game/
+├── public/
+│   ├── index.html          # HTML entry point
+│   └── assets/             # Static assets
+│       ├── models/         # 3D models
+│       ├── textures/       # Textures and images
+│       └── audio/          # Sound effects and music
+├── src/
+│   ├── main.js             # Game entry point
+│   ├── scenes/
+│   │   └── MainScene.js    # Three.js scene setup
+│   ├── components/
+│   │   ├── UI.js           # UI overlay (HUD, menus)
+│   │   └── GameLogic.js    # Game-specific logic
+│   └── utils/
+│       ├── InputManager.js # Keyboard/mouse/touch input
+│       └── AudioManager.js # Sound effects and music
+├── package.json
+├── vite.config.js
+└── README.md
+```
+
+## Development Workflow
+
+```bash
+# Start the dev server with hot reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview the production build
+npm run preview
+```
+
+## Configuration
+
+CLI configuration is stored in `~/.myvillage/config.json`:
+
+```json
+{
+  "apiBaseUrl": "https://portal.myvillageproject.ai/api/v1",
+  "oauthBaseUrl": "https://portal.myvillageproject.ai/api/oauth",
+  "clientId": "myvillage-cli",
+  "callbackPort": 3737
+}
+```
+
+Credentials are stored encrypted in `~/.myvillage/credentials.json` with restrictive file permissions.
+
+## Troubleshooting
+
+**"Authentication required" error:**
+Run `myvillage login` to authenticate before using other commands.
+
+**"Not a valid game project directory" error:**
+Make sure you're inside a game directory created with `myvillage create-game`. The `package.json` must contain a `myvillage` configuration block.
+
+**Browser doesn't open during login:**
+Copy the URL printed in the terminal and open it manually in your browser.
+
+**Port 3737 in use during login:**
+Close other applications using port 3737, or update `callbackPort` in `~/.myvillage/config.json`.
+
+## Support
+
+- **Technical Support**: dev@myvillageproject.ai
+- **General Inquiries**: info@myvillageproject.ai
+- **MyVillageOS Portal**: https://portal.myvillageproject.ai
+
+## License
+
+MIT

package/bin/myvillage.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@myvillage/cli",
+  "version": "1.0.0",
+  "description": "MyVillageOS CLI for student game developers",
+  "type": "module",
+  "bin": {
+    "myvillage": "./bin/myvillage.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "myvillage",
+    "myvillageos",
+    "cli",
+    "game",
+    "threejs",
+    "education",
+    "m-uni"
+  ],
+  "author": "MyVillage Project",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.1.0",
+    "inquirer": "^9.2.12",
+    "axios": "^1.6.2",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "open": "^10.0.3",
+    "conf": "^12.0.0",
+    "update-notifier": "^7.0.0"
+  }
+}

package/src/commands/create-game.js

@@ -0,0 +1,106 @@
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import { isAuthenticated } from '../utils/auth.js';
+import { createGameProject } from '../utils/templates.js';
+
+export async function createGameCommand() {
+  // Check authentication
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+
+  // Interactive prompts
+  const answers = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'type',
+      message: 'What type of game would you like to create?',
+      choices: [
+        { name: 'Quiz Game - Test knowledge with interactive questions', value: 'quiz' },
+        { name: 'Exploration Game - Navigate and discover', value: 'exploration' },
+        { name: 'Narrative Game - Story-driven experience', value: 'narrative' },
+        { name: 'Custom - Start with base Three.js template', value: 'custom' },
+      ],
+    },
+    {
+      type: 'input',
+      name: 'name',
+      message: 'Game name:',
+      default: 'My Game',
+      validate: (input) => {
+        if (!input.trim()) return 'Game name is required.';
+        return true;
+      },
+    },
+    {
+      type: 'input',
+      name: 'description',
+      message: 'Game description:',
+      default: 'An educational game built with Three.js',
+    },
+    {
+      type: 'list',
+      name: 'ageGroup',
+      message: 'Target age group:',
+      choices: [
+        { name: '5-8 years', value: '5-8' },
+        { name: '9-12 years', value: '9-12' },
+        { name: '13-15 years', value: '13-15' },
+        { name: '16-18 years', value: '16-18' },
+      ],
+    },
+  ]);
+
+  // Create project directory
+  const slug = answers.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+  const targetDir = resolve(process.cwd(), slug);
+
+  if (existsSync(targetDir)) {
+    console.log(chalk.red(`\n  \u2717 Directory "${slug}" already exists. Choose a different name or remove the existing directory.`));
+    return;
+  }
+
+  const spinner = ora('Creating game project...').start();
+
+  try {
+    // Generate project from template
+    createGameProject(targetDir, {
+      name: answers.name,
+      description: answers.description,
+      type: answers.type,
+      ageGroup: answers.ageGroup,
+    });
+
+    spinner.text = 'Installing dependencies...';
+
+    // Run npm install in the new project directory
+    execSync('npm install', {
+      cwd: targetDir,
+      stdio: 'pipe',
+    });
+
+    spinner.succeed(`Game "${answers.name}" created successfully!`);
+
+    // Display next steps
+    console.log();
+    console.log(chalk.green(`  \u2713 Game "${answers.name}" created successfully!`));
+    console.log();
+    console.log(chalk.dim('  Next steps:'));
+    console.log();
+    console.log(`    ${chalk.cyan('cd')} ${slug}`);
+    console.log(`    ${chalk.cyan('npm run dev')}      ${chalk.dim('- Start development server')}`);
+    console.log(`    ${chalk.cyan('npm run build')}    ${chalk.dim('- Build for production')}`);
+    console.log(`    ${chalk.cyan('myvillage deploy')} ${chalk.dim('- Deploy to MyVillageOS')}`);
+    console.log();
+    console.log(chalk.dim(`  Game type: ${answers.type} | Age group: ${answers.ageGroup}`));
+    console.log();
+  } catch (err) {
+    spinner.fail('Failed to create game project.');
+    console.error(chalk.red(`  ${err.message}`));
+  }
+}

package/src/commands/deploy.js

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, resolve, relative } from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+import ora from 'ora';
+import { isAuthenticated } from '../utils/auth.js';
+import { deployGame } from '../utils/api.js';
+
+function readPackageJson(dir) {
+  const pkgPath = join(dir, 'package.json');
+  if (!existsSync(pkgPath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+// Recursively collect files from a directory, returning { relativePath: base64Content }
+function collectBuildFiles(dir, baseDir) {
+  const files = {};
+
+  function walk(currentDir) {
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else {
+        const relPath = relative(baseDir, fullPath);
+        const content = readFileSync(fullPath);
+        files[relPath] = content.toString('base64');
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+export async function deployCommand() {
+  // Check authentication
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+
+  const projectDir = resolve(process.cwd());
+  const pkg = readPackageJson(projectDir);
+
+  // Verify this is a valid MyVillageOS game project
+  if (!pkg || !pkg.myvillage) {
+    console.log(chalk.red('  \u2717 Not a valid game project directory.'));
+    console.log(chalk.dim('  Make sure you are inside a game directory created with "myvillage create-game".'));
+    return;
+  }
+
+  const spinner = ora('Building game...').start();
+
+  try {
+    // Run production build
+    execSync('npm run build', {
+      cwd: projectDir,
+      stdio: 'pipe',
+    });
+
+    // Check that build output exists
+    const distDir = join(projectDir, 'dist');
+    if (!existsSync(distDir)) {
+      spinner.fail('Build completed but no dist/ directory found.');
+      return;
+    }
+
+    spinner.text = 'Packaging build artifacts...';
+
+    // Collect build files
+    const files = collectBuildFiles(distDir, distDir);
+
+    spinner.text = 'Deploying to MyVillageOS...';
+
+    // Upload to MyVillageOS API
+    const result = await deployGame({
+      name: pkg.name,
+      description: pkg.description || '',
+      category: pkg.myvillage.gameType || 'custom',
+      targetAge: pkg.myvillage.targetAge || 'all',
+      files,
+    });
+
+    spinner.succeed('Deployment complete!');
+    console.log();
+    console.log(chalk.green(`  \u2713 Deployed to ${result.url}`));
+
+    if (result.mvtAwarded) {
+      console.log(chalk.green(`  \u2713 You earned ${result.mvtAwarded} MVT tokens!`));
+    }
+
+    if (result.gameId) {
+      console.log(chalk.dim(`  Game ID: ${result.gameId}`));
+    }
+
+    console.log();
+  } catch (err) {
+    if (err.response) {
+      // API error
+      const message = err.response.data?.error_description
+        || err.response.data?.error
+        || err.response.data?.message
+        || 'Unknown server error';
+      spinner.fail(`Deployment failed: ${message}`);
+    } else if (err.stderr) {
+      // Build error
+      spinner.fail('Build failed.');
+      console.error(chalk.red(`  ${err.stderr.toString().trim()}`));
+    } else {
+      spinner.fail(`Deployment failed: ${err.message}`);
+    }
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,200 @@
+import { createServer } from 'http';
+import { randomBytes, createHash } from 'crypto';
+import chalk from 'chalk';
+import ora from 'ora';
+import open from 'open';
+import axios from 'axios';
+import { getConfig } from '../utils/config.js';
+import { saveCredentials, loadCredentials } from '../utils/auth.js';
+import { getUserInfo } from '../utils/api.js';
+
+// Generate PKCE code verifier (random 64-char hex string)
+function generateCodeVerifier() {
+  return randomBytes(32).toString('hex');
+}
+
+// Generate S256 code challenge from verifier
+function generateCodeChallenge(verifier) {
+  return createHash('sha256')
+    .update(verifier)
+    .digest('base64url');
+}
+
+export async function loginCommand() {
+  const config = getConfig();
+
+  // Check if already logged in
+  const existing = loadCredentials();
+  if (existing?.access_token) {
+    console.log(chalk.yellow('You are already logged in.'));
+    console.log(chalk.dim('Run "myvillage logout" first to log in with a different account.'));
+    return;
+  }
+
+  const spinner = ora('Preparing authentication...').start();
+
+  // Generate PKCE values and state token
+  const state = randomBytes(16).toString('hex');
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = generateCodeChallenge(codeVerifier);
+
+  // Build authorization URL
+  const params = new URLSearchParams({
+    client_id: config.clientId,
+    redirect_uri: `http://localhost:${config.callbackPort}/callback`,
+    response_type: 'code',
+    scope: 'openid profile email villager offline_access',
+    state,
+    code_challenge: codeChallenge,
+    code_challenge_method: 'S256',
+  });
+
+  const authUrl = `${config.oauthBaseUrl}/authorize?${params.toString()}`;
+
+  // Create a promise that resolves when we receive the OAuth callback
+  const authResult = await new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+      const url = new URL(req.url, `http://localhost:${config.callbackPort}`);
+
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      const code = url.searchParams.get('code');
+      const returnedState = url.searchParams.get('state');
+      const error = url.searchParams.get('error');
+      const errorDescription = url.searchParams.get('error_description');
+
+      // Send response to the browser
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      if (error) {
+        res.end(`
+          <html><body style="font-family: sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; background: #302017; color: #E4DCCB;">
+            <div style="text-align: center;">
+              <h1 style="color: #FF6B6B;">Authentication Failed</h1>
+              <p>${errorDescription || error}</p>
+              <p>You can close this window.</p>
+            </div>
+          </body></html>
+        `);
+      } else {
+        res.end(`
+          <html><body style="font-family: sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; background: #302017; color: #E4DCCB;">
+            <div style="text-align: center;">
+              <h1 style="color: #FFD700;">Success!</h1>
+              <p>You are now logged in to MyVillageOS CLI.</p>
+              <p>You can close this window and return to your terminal.</p>
+            </div>
+          </body></html>
+        `);
+      }
+
+      // Close the server
+      server.close();
+
+      if (error) {
+        reject(new Error(errorDescription || error));
+        return;
+      }
+
+      // Validate state parameter
+      if (returnedState !== state) {
+        reject(new Error('State mismatch - possible CSRF attack. Please try again.'));
+        return;
+      }
+
+      resolve(code);
+    });
+
+    server.listen(config.callbackPort, () => {
+      spinner.text = 'Opening browser for authentication...';
+
+      // Open browser to authorization URL
+      open(authUrl).catch(() => {
+        spinner.stop();
+        console.log(chalk.yellow('\nCould not open browser automatically.'));
+        console.log(chalk.dim('Please open this URL in your browser:'));
+        console.log(chalk.cyan(authUrl));
+      });
+
+      spinner.text = 'Waiting for authentication in browser...';
+    });
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        reject(new Error(`Port ${config.callbackPort} is already in use. Close other applications and try again.`));
+      } else {
+        reject(err);
+      }
+    });
+
+    // Timeout after 5 minutes
+    setTimeout(() => {
+      server.close();
+      reject(new Error('Authentication timed out. Please try again.'));
+    }, 5 * 60 * 1000);
+  }).catch((err) => {
+    spinner.fail(err.message);
+    return null;
+  });
+
+  if (!authResult) return;
+
+  // Exchange authorization code for tokens
+  spinner.text = 'Exchanging authorization code for tokens...';
+
+  try {
+    const tokenResponse = await axios.post(
+      `${config.oauthBaseUrl}/token`,
+      new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: authResult,
+        redirect_uri: `http://localhost:${config.callbackPort}/callback`,
+        client_id: config.clientId,
+        code_verifier: codeVerifier,
+      }),
+      {
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'User-Agent': 'MyVillageOS-CLI/1.0.0',
+        },
+      }
+    );
+
+    const { access_token, refresh_token, expires_in } = tokenResponse.data;
+
+    // Fetch user info
+    spinner.text = 'Fetching user info...';
+    const userInfo = await getUserInfo(access_token);
+
+    // Store credentials securely
+    saveCredentials({
+      access_token,
+      refresh_token,
+      expires_at: Date.now() + expires_in * 1000,
+      user_id: userInfo.sub,
+      user_email: userInfo.email,
+      user_name: userInfo.name,
+    });
+
+    spinner.succeed('Authentication complete!');
+    console.log();
+    console.log(chalk.green(`  \u2713 Successfully logged in as ${userInfo.email}`));
+
+    if (userInfo.villager) {
+      const v = userInfo.villager;
+      if (v.mvtBalance !== undefined) {
+        console.log(chalk.dim(`  MVT Balance: ${v.mvtBalance} tokens`));
+      }
+    }
+
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error_description
+      || err.response?.data?.error
+      || err.message;
+    spinner.fail(`Authentication failed: ${message}`);
+  }
+}

package/src/commands/logout.js

@@ -0,0 +1,12 @@
+import chalk from 'chalk';
+import { clearCredentials } from '../utils/auth.js';
+
+export async function logoutCommand() {
+  const removed = clearCredentials();
+
+  if (removed) {
+    console.log(chalk.green('  \u2713 Successfully logged out.'));
+  } else {
+    console.log(chalk.dim('  No stored credentials found. You are not logged in.'));
+  }
+}