uda-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UDA Contributors
+
+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,85 @@
+# UDA (Universal Dev AI)
+
+AI-agnostic context engineering + RAG CLI tool for game development.
+
+## Features
+
+- **Local RAG**: LanceDB + MiniLM embeddings - no API keys needed
+- **Multi-AI Support**: Claude, Cursor, Windsurf, AGENTS.md, Raw export
+- **Plugin System**: Git-based engine plugins (Unity, Godot, Unreal, etc.)
+- **Workflow Engine**: YAML-defined AI-assisted workflows
+- **Project Context**: Automatic knowledge base management
+
+## Installation
+
+```bash
+npm install -g uda
+```
+
+## Quick Start
+
+```bash
+# Initialize UDA in your project
+uda init
+
+# Scan and index knowledge
+uda scan
+
+# Search knowledge base
+uda search "MonoBehaviour lifecycle"
+
+# Export to your AI tool
+uda export --format claude
+```
+
+## Commands
+
+- `uda init` - Initialize UDA in current project
+- `uda sync` - Generate AI tool files from knowledge base
+- `uda search <query>` - Search knowledge base
+- `uda learn <source>` - Teach knowledge to RAG
+- `uda scan` - Scan project and index into RAG
+- `uda plugin <action>` - Manage engine plugins
+- `uda export --format <type>` - Export knowledge to specific format
+- `uda status` - Show UDA system status
+- `uda config [key] [value]` - Manage UDA settings
+
+## Supported Formats
+
+- **claude**: Generates CLAUDE.md and .claude/ skills
+- **cursor**: Generates .cursorrules
+- **agents-md**: Generates AGENTS.md
+- **raw**: Generates full-context.md
+
+## Plugin System
+
+Install engine-specific knowledge:
+
+```bash
+uda plugin add https://github.com/user/uda-plugin-unity.git
+uda plugin update unity
+uda plugin update-all
+```
+
+## Project Structure
+
+```
+.uda/
+├── config.json          # UDA configuration
+├── knowledge/
+│   ├── engine/          # Engine plugins (Unity, Godot, etc.)
+│   ├── project/         # Project-specific knowledge
+│   └── community/       # Community contributions
+├── workflows/           # AI-assisted workflows
+├── agents/              # Specialized AI agents
+├── state/
+│   ├── current.md       # Active work state
+│   ├── features/        # Feature specifications
+│   └── history/         # Completed work
+└── rag/
+    └── lancedb/         # Vector database
+```
+
+## License
+
+MIT

package/bin/uda.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { createCli } from '../src/cli.js';
+const program = createCli();
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "uda-cli",
+  "version": "0.2.0",
+  "description": "Universal Dev AI — AI-agnostic context engineering + RAG for game development",
+  "type": "module",
+  "main": "./src/cli.js",
+  "bin": {
+    "uda-cli": "./bin/uda.js",
+    "uda": "./bin/uda.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "!src/**/*.test.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage src/**/*.test.js",
+    "dev": "node bin/uda.js"
+  },
+  "keywords": [
+    "ai",
+    "context-engineering",
+    "rag",
+    "game-dev",
+    "unity",
+    "godot",
+    "unreal",
+    "cli",
+    "vector-database",
+    "embeddings"
+  ],
+  "author": "UDA Contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "@xenova/transformers": "^2.17.2",
+    "commander": "^14.0.3",
+    "simple-git": "^3.32.3",
+    "yaml": "^2.8.2"
+  }
+}

package/src/adapters/agents-md.js

@@ -0,0 +1,22 @@
+export class AgentsMdAdapter {
+  get name() { return 'agents-md'; }
+  detect() { return true; }
+
+  generate(knowledge, workflows, agents) {
+    const lines = ['# AGENTS.md', '', '> Generated by UDA (Universal Dev AI)', ''];
+
+    if (knowledge.conventions?.length > 0) {
+      lines.push('## Coding Conventions');
+      knowledge.conventions.forEach(c => lines.push(`- ${c}`));
+      lines.push('');
+    }
+
+    if (knowledge.decisions?.length > 0) {
+      lines.push('## Architecture');
+      knowledge.decisions.forEach(d => lines.push(`- ${d}`));
+      lines.push('');
+    }
+
+    return { 'AGENTS.md': lines.join('\n') };
+  }
+}

package/src/adapters/base.js

@@ -0,0 +1,14 @@
+// src/adapters/base.js
+export class BaseAdapter {
+  constructor() {
+    if (new.target === BaseAdapter) {
+      throw new Error('BaseAdapter is abstract');
+    }
+  }
+
+  get name() { throw new Error('Not implemented'); }
+
+  detect(projectRoot) { throw new Error('Not implemented'); }
+
+  generate(knowledge, workflows, agents, projectRoot) { throw new Error('Not implemented'); }
+}

package/src/adapters/claude.js

@@ -0,0 +1,138 @@
+// src/adapters/claude.js
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+export class ClaudeAdapter {
+  get name() { return 'claude'; }
+
+  detect(projectRoot) {
+    return (
+      existsSync(join(projectRoot, 'CLAUDE.md')) ||
+      existsSync(join(projectRoot, '.claude'))
+    );
+  }
+
+  generate(knowledge, workflows, agents, projectRoot, capabilities = {}) {
+    const files = {};
+    files['CLAUDE.md'] = this._generateClaudeMd(knowledge, workflows, capabilities);
+
+    for (const wf of workflows) {
+      const skillPath = `.claude/commands/uda/${wf.name}.md`;
+      files[skillPath] = this._generateSkill(wf);
+    }
+
+    for (const agent of agents) {
+      const agentPath = `.claude/agents/uda-${agent.name}.md`;
+      files[agentPath] = this._generateAgent(agent);
+    }
+
+    return files;
+  }
+
+  _generateClaudeMd(knowledge, workflows, capabilities) {
+    const lines = ['# CLAUDE.md', ''];
+
+    // Project info
+    if (knowledge.project) {
+      lines.push('## Project Info');
+      if (knowledge.project.name) lines.push(`- **Project**: ${knowledge.project.name}`);
+      if (knowledge.project.engine) lines.push(`- **Engine**: ${knowledge.project.engine}`);
+      if (knowledge.project.version) lines.push(`- **Version**: ${knowledge.project.version}`);
+      lines.push('');
+    }
+
+    if (knowledge.conventions?.length > 0) {
+      lines.push('## Conventions');
+      for (const conv of knowledge.conventions) lines.push(`- ${conv}`);
+      lines.push('');
+    }
+
+    if (knowledge.decisions?.length > 0) {
+      lines.push('## Architectural Decisions');
+      for (const dec of knowledge.decisions) lines.push(`- ${dec}`);
+      lines.push('');
+    }
+
+    // UDA AI-native instructions
+    lines.push('## UDA (Universal Dev AI)');
+    lines.push('');
+    lines.push('This project uses UDA for AI-assisted development. Follow these rules:');
+    lines.push('');
+
+    // Knowledge base instructions
+    lines.push('### Knowledge Base');
+    lines.push('- Engine knowledge is in `.uda/knowledge/`');
+    lines.push('- For engine questions, check these files FIRST');
+    lines.push('- For broader searches: `npx uda-cli search "query"`');
+    lines.push('');
+
+    // Log instructions (only if capability exists)
+    if (capabilities.logs) {
+      lines.push('### Console Logs');
+      lines.push(`- Log file: \`${capabilities.logs.source || '.uda/logs/console.jsonl'}\``);
+      lines.push('- Read logs: `npx uda-cli logs --errors --last 50`');
+      lines.push('- When user mentions logs, errors, or console issues, run this command');
+      lines.push('');
+    }
+
+    // Available commands
+    lines.push('### Available Commands');
+    lines.push('- `npx uda-cli search "query"` — search knowledge base');
+    if (capabilities.logs) {
+      lines.push('- `npx uda-cli logs [--errors|--warnings] [--last N]` — read engine logs');
+    }
+    lines.push('- `npx uda-cli plugin add <repo>` — add new plugin');
+    lines.push('- `npx uda-cli sync` — regenerate AI tool files');
+    lines.push('');
+
+    // Workflow skills
+    if (workflows.length > 0) {
+      lines.push('### UDA Skills');
+      for (const wf of workflows) {
+        lines.push(`- \`/uda:${wf.name}\` — ${wf.description}`);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  _generateSkill(workflow) {
+    const lines = [
+      '---',
+      `description: ${workflow.description}`,
+      '---',
+      '',
+      `# ${workflow.name}`,
+      '',
+    ];
+
+    if (workflow.steps) {
+      for (const step of workflow.steps) {
+        lines.push(`## ${step.name || step.id}`);
+        if (step.questions) {
+          for (const q of step.questions) {
+            lines.push(`- "${q}"`);
+          }
+        }
+        lines.push('');
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  _generateAgent(agent) {
+    return [
+      '---',
+      `name: uda-${agent.name}`,
+      `description: ${agent.description}`,
+      `tools: ${agent.tools || 'Read, Grep, Glob'}`,
+      `model: ${agent.model || 'sonnet'}`,
+      '---',
+      '',
+      agent.prompt || `You are a ${agent.description}.`,
+      '',
+    ].join('\n');
+  }
+}

package/src/adapters/cursor.js

@@ -0,0 +1,46 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+export class CursorAdapter {
+  get name() { return 'cursor'; }
+
+  detect(projectRoot) {
+    return (
+      existsSync(join(projectRoot, '.cursorrules')) ||
+      existsSync(join(projectRoot, '.cursor'))
+    );
+  }
+
+  generate(knowledge, workflows, agents, projectRoot) {
+    const files = {};
+    files['.cursorrules'] = this._generateRules(knowledge);
+    return files;
+  }
+
+  _generateRules(knowledge) {
+    const lines = [];
+
+    if (knowledge.project) {
+      lines.push(`Project: ${knowledge.project.name || 'Unknown'}`);
+      lines.push(`Engine: ${knowledge.project.engine || 'Unknown'}`);
+      lines.push('');
+    }
+
+    if (knowledge.conventions?.length > 0) {
+      lines.push('## Conventions');
+      for (const conv of knowledge.conventions) {
+        lines.push(`- ${conv}`);
+      }
+      lines.push('');
+    }
+
+    if (knowledge.decisions?.length > 0) {
+      lines.push('## Architecture');
+      for (const dec of knowledge.decisions) {
+        lines.push(`- ${dec}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+}

package/src/adapters/raw.js

@@ -0,0 +1,34 @@
+export class RawAdapter {
+  get name() { return 'raw'; }
+  detect() { return true; } // always available
+
+  generate(knowledge, workflows, agents) {
+    const lines = ['# Project Context (UDA Generated)', ''];
+
+    if (knowledge.project) {
+      lines.push(`## Project: ${knowledge.project.name || 'Unknown'}`);
+      lines.push(`Engine: ${knowledge.project.engine || 'N/A'}`);
+      lines.push('');
+    }
+
+    if (knowledge.conventions?.length > 0) {
+      lines.push('## Conventions');
+      knowledge.conventions.forEach(c => lines.push(`- ${c}`));
+      lines.push('');
+    }
+
+    if (knowledge.decisions?.length > 0) {
+      lines.push('## Decisions');
+      knowledge.decisions.forEach(d => lines.push(`- ${d}`));
+      lines.push('');
+    }
+
+    if (workflows.length > 0) {
+      lines.push('## Available Workflows');
+      workflows.forEach(w => lines.push(`- **${w.name}**: ${w.description}`));
+      lines.push('');
+    }
+
+    return { '.uda/.generated/full-context.md': lines.join('\n') };
+  }
+}

package/src/adapters/registry.js

@@ -0,0 +1,18 @@
+// src/adapters/registry.js
+const adapters = [];
+
+export function registerAdapter(adapter) {
+  adapters.push(adapter);
+}
+
+export function getAdapter(name) {
+  return adapters.find(a => a.name === name);
+}
+
+export function detectAdapters(projectRoot) {
+  return adapters.filter(a => a.detect(projectRoot));
+}
+
+export function getAllAdapters() {
+  return [...adapters];
+}

package/src/cli.js

@@ -0,0 +1,106 @@
+import { Command } from 'commander';
+import { handleLearn } from './commands/learn.js';
+import { handleSearch } from './commands/search.js';
+import { handleScan } from './commands/scan.js';
+import { handleSync } from './commands/sync.js';
+import { handleInit } from './commands/init.js';
+import { handlePluginAdd, handlePluginList, handlePluginRemove } from './commands/plugin.js';
+import { handleStatus } from './commands/status.js';
+import { handleConfig } from './commands/config.js';
+import { handlePluginUpdate } from './commands/plugin.js';
+import { handleExport } from './commands/export.js';
+import { handleLogs } from './commands/logs.js';
+
+export function createCli() {
+  const program = new Command();
+
+  program
+    .command('init')
+    .description('Initialize UDA in current project')
+    .option('-e, --engine <name>', 'Engine plugin to install (e.g. unity)')
+    .action(handleInit);
+
+  program
+    .command('sync')
+    .description('Generate AI tool files from knowledge base')
+    .action(handleSync);
+
+  program
+    .command('search <query>')
+    .description('Search knowledge base')
+    .option('-t, --top <number>', 'Number of results', '5')
+    .option('-f, --format <format>', 'Output format (terminal, md, clipboard)', 'terminal')
+    .action(handleSearch);
+
+  program
+    .command('learn <source>')
+    .description('Teach knowledge to RAG')
+    .option('--type <type>', 'Knowledge type (bug-fix, feature, pattern, knowledge)', 'knowledge')
+    .option('--tags <tags>', 'Comma-separated tags')
+    .action(handleLearn);
+
+  program
+    .command('scan')
+    .description('Scan project and index into RAG')
+    .action(handleScan);
+
+  const pluginCmd = program
+    .command('plugin')
+    .description('Manage engine plugins');
+
+  pluginCmd
+    .command('add <repo>')
+    .description('Install plugin from git repo')
+    .action(handlePluginAdd);
+
+  pluginCmd
+    .command('list')
+    .description('List installed plugins')
+    .action(handlePluginList);
+
+  pluginCmd
+    .command('remove <name>')
+    .description('Remove a plugin')
+    .action(handlePluginRemove);
+
+  pluginCmd
+    .command('update [name]')
+    .description('Update plugin(s)')
+    .action(handlePluginUpdate);
+
+  pluginCmd
+    .command('create <name>')
+    .description('Scaffold a new plugin')
+    .action(async (name) => {
+      console.log('uda plugin create — not yet implemented');
+    });
+
+  program
+    .command('export')
+    .description('Export knowledge to specific format')
+    .requiredOption('-f, --format <format>', 'Output format (claude, cursor, agents-md, raw)')
+    .option('-o, --output <path>', 'Output directory')
+    .action(handleExport);
+
+  program
+    .command('status')
+    .description('Show UDA system status')
+    .action(handleStatus);
+
+  program
+    .command('config')
+    .description('Manage UDA settings')
+    .argument('[key]', 'Config key to get/set')
+    .argument('[value]', 'Value to set')
+    .action(handleConfig);
+
+  program
+    .command('logs')
+    .description('Read engine console logs')
+    .option('-e, --errors', 'Show only errors')
+    .option('-w, --warnings', 'Show only warnings')
+    .option('-l, --last <count>', 'Show last N entries')
+    .action(handleLogs);
+
+  return program;
+}

package/src/commands/config.js

@@ -0,0 +1,55 @@
+// src/commands/config.js
+import { loadConfig, saveConfig, getConfigValue, setConfigValue } from '../core/config.js';
+import { validateConfigKey } from '../core/validators.js';
+
+export async function handleConfig(key, value) {
+  const root = process.cwd();
+
+  // Validate config key format if provided
+  if (key) {
+    const v = validateConfigKey(key);
+    if (!v.valid) {
+      console.error(`✘ ${v.error}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  let config;
+  try {
+    config = await loadConfig(root);
+  } catch (err) {
+    console.error(`✘ Failed to load config: ${err.message}`);
+    console.error('  Run `uda init` to initialize the project.');
+    process.exitCode = 1;
+    return;
+  }
+
+  // No key — list all config
+  if (!key) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+
+  // Key only — get value
+  if (value === undefined) {
+    const result = getConfigValue(config, key);
+    if (result === undefined) {
+      console.error(`✘ Key "${key}" not found`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(typeof result === 'object' ? JSON.stringify(result, null, 2) : result);
+    return;
+  }
+
+  // Key + value — set value
+  try {
+    setConfigValue(config, key, value);
+    await saveConfig(root, config);
+    console.log(`✔ ${key} = ${JSON.stringify(getConfigValue(config, key))}`);
+  } catch (err) {
+    console.error(`✘ Failed to save config: ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/export.js

@@ -0,0 +1,77 @@
+// src/commands/export.js
+import { writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { udaPaths } from '../core/constants.js';
+import { loadConfig } from '../core/config.js';
+import { loadKnowledge, loadWorkflows, loadAgents } from '../core/knowledge-loader.js';
+import { ClaudeAdapter } from '../adapters/claude.js';
+import { CursorAdapter } from '../adapters/cursor.js';
+import { RawAdapter } from '../adapters/raw.js';
+import { AgentsMdAdapter } from '../adapters/agents-md.js';
+import { validateExportFormat } from '../core/validators.js';
+
+const ADAPTER_MAP = {
+  claude: () => new ClaudeAdapter(),
+  cursor: () => new CursorAdapter(),
+  'agents-md': () => new AgentsMdAdapter(),
+  raw: () => new RawAdapter(),
+};
+
+export async function handleExport(options) {
+  const root = process.cwd();
+  const paths = udaPaths(root);
+  const format = options.format;
+
+  // Validate format
+  const fv = validateExportFormat(format);
+  if (!fv.valid) {
+    console.error(`✘ ${fv.error}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const createAdapter = ADAPTER_MAP[format];
+  if (!createAdapter) {
+    console.error(`✘ Unknown format "${format}". Available: ${Object.keys(ADAPTER_MAP).join(', ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let adapter, knowledge, workflows, agents;
+  try {
+    adapter = createAdapter();
+    knowledge = await loadKnowledge(paths);
+    workflows = await loadWorkflows(paths);
+    agents = await loadAgents(paths);
+  } catch (err) {
+    console.error(`✘ Failed to load knowledge base: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let files;
+  try {
+    files = adapter.generate(knowledge, workflows, agents, root);
+  } catch (err) {
+    console.error(`✘ Failed to generate ${format} output: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Determine output base directory
+  const outputBase = options.output || join(paths.generated, format);
+
+  let totalFiles = 0;
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = join(outputBase, filePath);
+    try {
+      await mkdir(dirname(fullPath), { recursive: true });
+      await writeFile(fullPath, content);
+      totalFiles++;
+    } catch (err) {
+      console.error(`  ✘ Failed to write ${filePath}: ${err.message}`);
+    }
+  }
+
+  console.log(`✔ Exported ${totalFiles} files (${format}) → ${outputBase}`);
+}