@crystalplatforms/adm 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 CrystalGamesStudio
+
+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,210 @@
+# ADM CLI
+
+**ADM** is a TUI-only developer tool that automates environment setup on new machines and provides an AI-powered daily assistant for development workflows. One command — `adm` — opens a full-screen terminal interface where everything happens: AI chat, setup, GitHub/GitLab management, tool installation, and configuration.
+
+Targets Node.js/web developers on macOS, Linux, and Windows — reducing initial dev setup from hours to minutes while staying available as an intelligent companion throughout development.
+
+---
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g @crystalgames/adm
+```
+
+### macOS / Linux (curl)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/CrystalGamesStudio/ADM-CLI/main/scripts/installer.sh | sh
+```
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap CrystalGamesStudio/tap
+brew install CrystalGamesStudio/tap/adm
+```
+
+### Windows (PowerShell)
+
+```powershell
+irm https://raw.githubusercontent.com/CrystalGamesStudio/ADM-CLI/main/scripts/install.ps1 | iex
+```
+
+**Prerequisites:** Node.js 18+ must be installed. The curl and PowerShell installers will check for this and provide installation instructions if missing.
+
+---
+
+## Quick Start
+
+```bash
+# Launch full-screen TUI
+adm
+
+# Inside the TUI:
+/help            — Show all commands
+/ai              — Toggle AI mode (blue input, chat with GLM)
+/ai <question>   — One-off AI query without toggling mode
+/github status   — GitHub status
+/gitlab status   — GitLab status
+/download        — Launch extension setup wizard
+/feedback        — Open feedback page in browser
+/theme cyberpunk — Switch theme
+/exit            — Quit ADM
+```
+
+---
+
+## TUI Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show command reference |
+| `/exit` | Exit ADM |
+| `/clear` | Clear message history |
+| `/theme` | List or switch themes (dark, light, cyberpunk, nord, forest, monokai) |
+| `/config` | Show current configuration |
+| `/ai` | Toggle AI mode ON/OFF — input turns blue, questions go to GLM API |
+| `/ai <question>` | One-off AI query without toggling mode |
+| `/model` | Show or switch AI provider |
+| `/github` | GitHub operations: status, pr, issue, commit |
+| `/gitlab` | GitLab operations: status, mr, issue, commit |
+| `/download` | Launch extension setup wizard |
+| `/feedback` | Open feedback page in browser |
+| `/connect` | Connect to GitHub or GitLab |
+| `/dotfiles` | Sync dotfiles from repo |
+| `/upgrade` | Check for and install updates |
+
+### AI Mode
+
+When AI mode is ON (`/ai`):
+- Input bar turns **blue** with `AI>` prompt
+- Status bar shows **AI: ON** (green)
+- Everything typed goes directly to GLM API
+- Responses appear with **GLM:** prefix
+- Press `Esc` or type `exit` to leave AI mode
+
+AI knowledge system: on first run, ADM reads its own docs (README, PRD) and caches a compact summary in `~/.adm/ai-knowledge.json`. This knowledge is injected as a system message in every AI query, so the AI knows about ADM itself. Cache auto-updates when ADM version changes.
+
+---
+
+## Technical Architecture
+
+### Stack
+- **Runtime**: Node.js 18+
+- **TUI**: ink v5 + React 18 (full-screen terminal UI)
+- **AI**: GLM API (Zhipu AI) — `glm-4.7-flash` model with automatic fallback
+- **GitHub**: `@octokit/rest`
+- **Styling**: chalk v4, 6 built-in themes
+- **Testing**: Jest
+
+### Project Structure
+
+```
+src/
+├── tui/                          # Full-screen TUI (ink + React)
+│   ├── app.js                    # Main App component (status bar, messages, input)
+│   ├── app-state.js              # State management + AI mode logic
+│   └── commands/
+│       └── registry.js           # Unified command dispatch + autocomplete
+├── ai/
+│   └── knowledge.js              # AI knowledge cache (reads docs, invalidates on version)
+├── integrations/
+│   ├── ai-backend.js             # GLM API client (query, retry, fallback models)
+│   ├── github.js                 # GitHub API (PRs, issues)
+│   └── gitlab.js                 # GitLab API (MRs, issues)
+├── installer/                    # Node.js, package managers, system packages
+├── config/                       # Configuration system (~/.adm/config.json)
+├── plugins/                      # Plugin loader (~/.adm/plugins/)
+├── ui/                           # Themes, ASCII clock, animations, spinner
+└── utils/                        # Keychain, encryption, dotfiles sync, fuzzy search
+```
+
+### User State
+
+```
+~/.adm/
+├── config.json          — Settings (theme, AI provider, tokens)
+├── ai-knowledge.json    — Cached ADM docs for AI context
+├── plugins/             — Custom command plugins (.js)
+├── tokens.enc           — Encrypted service tokens
+└── history              — Command history
+```
+
+---
+
+## Key Features
+
+### Full-Screen TUI
+Single `adm` command launches an ink-based terminal UI with:
+- **Status bar** — theme name, AI mode indicator, version
+- **Message area** — scrollable command output and AI responses
+- **Input bar** — green `>` prompt (blue `AI>` in AI mode)
+
+### AI Mode + Knowledge
+- `/ai` toggles continuous AI chat mode
+- `/ai <question>` for one-off queries
+- GLM API with automatic model fallback on rate limits
+- Knowledge system: ADM docs cached and injected as AI context
+- Friendly error messages on API failures
+
+### 6 Themes
+dark (default), light, cyberpunk, nord, forest, monokai — switch with `/theme <name>`
+
+### GitHub & GitLab Integration
+- `/github` — PR listing, creation, commenting, issues
+- `/gitlab` — MR listing, creation, commenting, issues
+- Secure token storage (OS keychain on macOS, encrypted file on Linux)
+
+### Extension Setup Wizard
+`/download` launches an interactive wizard that installs:
+- Node.js (via nvm wrapper)
+- Package managers (pnpm, npm)
+- Build tools (Vite, esbuild)
+- System packages (git, gh CLI)
+- SSH keys (ED25519)
+- Git config (user.name, user.email)
+- Dotfiles sync from repo
+
+### Feedback
+`/feedback` opens the feedback page in your default browser.
+
+### Plugin System
+Drop `.js` files in `~/.adm/plugins/` — each exports `{ execute(args, context) }` to add custom commands.
+
+### Dotfiles Sync
+`/dotfiles sync` — clone/sync dotfiles from a git repo, apply symlinks or copies for `.bashrc`, `.zshrc`, `.gitconfig`, `.ssh/config`.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run TUI locally
+npm start
+
+# Run specific test suite
+npx jest tests/unit/tui/ --no-coverage
+
+# Link globally for development
+npm link
+```
+
+### Test Structure
+- `tests/unit/` — Unit tests
+- `tests/integration/` — Integration tests
+- `tests/e2e/` — End-to-end smoke tests
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/adm

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+const chalk = require('chalk');
+const { handleAdmError, formatError } = require('../src/utils/error-handler');
+
+const pkg = require('../package.json');
+const args = process.argv.slice(2);
+
+// ── adm -v / adm --version ──────────────────────────────────
+if (args[0] === '-v' || args[0] === '--version') {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+// ── adm (no args) → TUI ────────────────────────────────────
+if (args.length === 0) {
+  const { boot } = require('../src/tui/app');
+  boot().catch(err => {
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  });
+  return;
+}
+
+// ── unknown command ──────────────────────────────────────────
+console.error(chalk.red(`Unknown command: ${args[0]}. Run ${chalk.bold('adm --help')} for available commands.`));
+process.exit(1);

package/bin/adm-tui

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * ADM TUI — Full-screen terminal UI
+ * Replaces Commander.js CLI with ink-based TUI for v2.
+ */
+'use strict';
+
+const { boot } = require('../src/tui/app');
+
+boot().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@crystalplatforms/adm",
+  "version": "0.2.3",
+  "description": "ADM developer CLI — environment setup, GitHub integration, and AI-powered daily assistant",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CrystalGamesStudio/ADM-CLI.git"
+  },
+  "homepage": "https://github.com/CrystalGamesStudio/ADM-CLI#readme",
+  "bugs": {
+    "url": "https://github.com/CrystalGamesStudio/ADM-CLI/issues"
+  },
+  "bin": {
+    "adm": "bin/adm"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/completion/",
+    "scripts/install.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node ./bin/adm",
+    "test": "jest --config=jest.config.js",
+    "test:unit": "jest tests/unit --runInBand",
+    "test:integration": "jest tests/integration --runInBand",
+    "test:shell": "echo 'Install bats separately to run shell tests' && exit 0",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "setup",
+    "github",
+    "gitlab",
+    "ai",
+    "adm"
+  ],
+  "dependencies": {
+    "@octokit/rest": "^20.0.2",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "execa": "^7.1.1",
+    "ink": "^5.2.1",
+    "inquirer": "^8.2.6",
+    "ora": "^5.4.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "jest": "^29.6.0",
+    "mock-fs": "^5.2.0",
+    "sinon": "^15.2.0"
+  }
+}

package/scripts/completion/adm.bash

@@ -0,0 +1,81 @@
+# Bash completion for adm (TUI mode — all commands use / prefix)
+_adm_completion() {
+  local cur prev
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  local commands="help exit clear theme config status ai model setup connect pr mr issue commit clock dotfiles uninstall plugins"
+
+  # Top-level completion (first word or after adm)
+  if [[ ${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${commands}" -- ${cur}) )
+    return 0
+  fi
+
+  # Subcommands
+  case "${COMP_WORDS[1]}" in
+    help|exit|clear|uninstall|plugins|status)
+      return 0
+      ;;
+    setup)
+      COMPREPLY=( $(compgen -W "--dry-run" -- ${cur}) )
+      return 0
+      ;;
+    connect)
+      local connect_subs="github gitlab list disconnect"
+      if [[ ${COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "${connect_subs}" -- ${cur}) )
+      elif [[ "${COMP_WORDS[2]}" == "github" || "${COMP_WORDS[2]}" == "gitlab" ]]; then
+        COMPREPLY=( $(compgen -W "--token" -- ${cur}) )
+      fi
+      return 0
+      ;;
+    pr)
+      local pr_subs="list draft comment"
+      if [[ ${COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "${pr_subs}" -- ${cur}) )
+      fi
+      return 0
+      ;;
+    mr)
+      local mr_subs="list draft comment"
+      if [[ ${COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "${mr_subs}" -- ${cur}) )
+      fi
+      return 0
+      ;;
+    issue)
+      COMPREPLY=( $(compgen -W "list" -- ${cur}) )
+      return 0
+      ;;
+    commit)
+      COMPREPLY=( $(compgen -W "suggest" -- ${cur}) )
+      return 0
+      ;;
+    theme)
+      local themes="dark light cyberpunk nord forest monokai"
+      COMPREPLY=( $(compgen -W "${themes}" -- ${cur}) )
+      return 0
+      ;;
+    model)
+      local providers="glm-free glm-pro openai anthropic ollama list"
+      COMPREPLY=( $(compgen -W "${providers}" -- ${cur}) )
+      return 0
+      ;;
+    dotfiles)
+      COMPREPLY=( $(compgen -W "sync --repo --copy" -- ${cur}) )
+      return 0
+      ;;
+    clock)
+      return 0
+      ;;
+    ai)
+      return 0
+      ;;
+    config)
+      return 0
+      ;;
+  esac
+}
+complete -F _adm_completion adm

package/scripts/completion/adm.zsh

@@ -0,0 +1,89 @@
+#compdef adm
+
+_adm() {
+  local -a commands subcommands opts
+
+  commands=(
+    'help:Show command reference'
+    'exit:Exit ADM'
+    'clear:Clear message history'
+    'theme:List or switch themes'
+    'config:Show current configuration'
+    'status:Show git status'
+    'ai:Toggle AI mode or ask a question'
+    'model:Show or switch AI provider'
+    'setup:Launch extension setup wizard'
+    'connect:Connect to GitHub or GitLab'
+    'pr:Pull request operations'
+    'mr:Merge request operations (GitLab)'
+    'issue:List issues from connected platform'
+    'commit:Commit subcommands'
+    'clock:Show ASCII clock'
+    'dotfiles:Sync dotfiles from repo'
+    'uninstall:Remove ADM CLI config'
+    'plugins:List loaded plugins'
+  )
+
+  _arguments -C \
+    '1:command:->command' \
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'command' commands
+      ;;
+    args)
+      case $words[1] in
+        setup)
+          _arguments '--dry-run[Preview planned actions without executing]'
+          ;;
+        connect)
+          local -a connect_subs
+          connect_subs=('github:Connect GitHub account' 'gitlab:Connect GitLab account' 'list:List connected services' 'disconnect:Disconnect a service')
+          if (( CURRENT == 2 )); then
+            _describe 'subcommand' connect_subs
+          else
+            case $words[2] in
+              github|gitlab) _arguments '--token[Access token]:token:' ;;
+            esac
+          fi
+          ;;
+        pr)
+          local -a pr_subs
+          pr_subs=('list:List open pull requests' 'draft:Create a draft PR' 'comment:Comment on a pull request')
+          if (( CURRENT == 2 )); then
+            _describe 'subcommand' pr_subs
+          fi
+          ;;
+        mr)
+          local -a mr_subs
+          mr_subs=('list:List open merge requests' 'draft:Create a draft MR' 'comment:Comment on a merge request')
+          if (( CURRENT == 2 )); then
+            _describe 'subcommand' mr_subs
+          fi
+          ;;
+        issue)
+          _arguments '1:subcommand:(list)'
+          ;;
+        commit)
+          _arguments '1:subcommand:(suggest)'
+          ;;
+        dotfiles)
+          local -a dotfiles_subs
+          dotfiles_subs=('sync:Clone/pull dotfiles repo and symlink files')
+          if (( CURRENT == 2 )); then
+            _describe 'subcommand' dotfiles_subs
+          fi
+          ;;
+        theme)
+          _arguments '1:theme:(dark light cyberpunk nord forest monokai)'
+          ;;
+        model)
+          _arguments '1:provider:(glm-free glm-pro openai anthropic ollama list)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_adm "$@"

package/scripts/install.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+const chalk = require('chalk');
+console.log('');
+console.log(chalk.green('  ADM CLI installed successfully!'));
+console.log('');
+console.log('  Run ' + chalk.bold('adm') + ' to launch the TUI.');
+console.log('  Type ' + chalk.bold('/download') + ' inside ADM to set up your dev environment.');
+console.log('');

package/src/ai/knowledge.js

@@ -0,0 +1,61 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const KNOWLEDGE_DIR = path.join(os.homedir(), '.adm');
+const KNOWLEDGE_FILE = path.join(KNOWLEDGE_DIR, 'ai-knowledge.json');
+
+const SOURCE_DOCS = ['README.md', path.join('plans', 'prd-v2.md')];
+
+function buildKnowledge(version, projectRoot) {
+  const parts = [];
+
+  for (const doc of SOURCE_DOCS) {
+    const filePath = path.join(projectRoot, doc);
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      // Take first 500 chars per doc for compactness
+      const compact = content.substring(0, 500).trim();
+      if (compact) {
+        parts.push(`--- ${path.basename(doc)} ---\n${compact}`);
+      }
+    } catch {
+      // doc missing — skip
+    }
+  }
+
+  if (parts.length === 0) return null;
+
+  const summary = parts.join('\n\n');
+  const cache = {
+    version,
+    summary,
+    updatedAt: new Date().toISOString(),
+  };
+
+  // Ensure ~/.adm/ exists
+  if (!fs.existsSync(KNOWLEDGE_DIR)) {
+    fs.mkdirSync(KNOWLEDGE_DIR, { recursive: true });
+  }
+  fs.writeFileSync(KNOWLEDGE_FILE, JSON.stringify(cache, null, 2), 'utf8');
+
+  return summary;
+}
+
+function getKnowledge(version, projectRoot) {
+  // Try reading cache
+  try {
+    const raw = fs.readFileSync(KNOWLEDGE_FILE, 'utf8');
+    const cached = JSON.parse(raw);
+    if (cached.version === version) {
+      return cached.summary;
+    }
+    // Version changed — rebuild
+  } catch {
+    // No cache — build fresh
+  }
+
+  return buildKnowledge(version, projectRoot);
+}
+
+module.exports = { getKnowledge, buildKnowledge, KNOWLEDGE_DIR, KNOWLEDGE_FILE };

package/src/commands/connect.js

@@ -0,0 +1,76 @@
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const ora = require('ora');
+const github = require('../integrations/github');
+const gitlab = require('../integrations/gitlab');
+const { listStoredServices, retrieveToken } = require('../utils/keychain');
+
+async function connectGithub({ token } = {}) {
+  if (!token) {
+    ({ token } = await inquirer.prompt([{
+      type: 'password',
+      name: 'token',
+      message: 'Enter GitHub Personal Access Token (PAT):',
+      mask: '*',
+    }]));
+  }
+  const s = ora('Validating GitHub token...').start();
+  try {
+    const result = await github.connect(token);
+    s.succeed(`Connected to GitHub as ${chalk.green(result.user.login)}`);
+    return { ok: true, user: result.user.login };
+  } catch (err) {
+    s.fail(err.message);
+    throw err;
+  }
+}
+
+async function listConnections() {
+  const services = await listStoredServices();
+  if (services.length === 0) {
+    console.log(chalk.yellow('  No connected services.'));
+    return [];
+  }
+  for (const name of services) {
+    const token = await retrieveToken(name);
+    const masked = token ? token.substring(0, 4) + '****' + token.slice(-4) : '(none)';
+    console.log(`  ${chalk.green(name)}: connected (token: ${masked})`);
+  }
+  return services;
+}
+
+async function disconnect(service) {
+  if (service === 'github') {
+    await github.disconnect();
+    console.log(chalk.green('  GitHub disconnected.'));
+    return true;
+  }
+  if (service === 'gitlab') {
+    await gitlab.disconnect();
+    console.log(chalk.green('  GitLab disconnected.'));
+    return true;
+  }
+  throw new Error(`Unknown service: ${service}. Supported: github, gitlab`);
+}
+
+async function connectGitlab({ token } = {}) {
+  if (!token) {
+    ({ token } = await inquirer.prompt([{
+      type: 'password',
+      name: 'token',
+      message: 'Enter GitLab Access Token:',
+      mask: '*',
+    }]));
+  }
+  const s = ora('Validating GitLab token...').start();
+  try {
+    const result = await gitlab.connect(token);
+    s.succeed(`Connected to GitLab as ${chalk.green(result.user.username)}`);
+    return { ok: true, user: result.user.username };
+  } catch (err) {
+    s.fail(err.message);
+    throw err;
+  }
+}
+
+module.exports = { connectGithub, connectGitlab, listConnections, disconnect };