vexi-cli 0.5.1

package/dist/scanner/index.js

@@ -0,0 +1,230 @@
+/**
+ * Project scanner — Feature 2: Full Project Understanding.
+ *
+ * On startup Vexi walks the project tree and builds a compact map of the
+ * codebase: languages, frameworks, architecture layers (frontend / backend /
+ * database / auth / devops) and the file tree. The result is cached in
+ * .vexi/project.json and a short text summary is injected into every AI
+ * prompt so the model understands the whole project, not just one file.
+ *
+ * Safeguards (prevent context flooding):
+ * - Respects .gitignore rules by default
+ * - Always excludes node_modules, .git, dist, build, coverage, etc.
+ * - Ignores files larger than MAX_FILE_SIZE (500KB)
+ * - Caps the number of files included in the summary
+ */
+import { promises as fs } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { readJson, writeJsonAtomic } from '../utils/fs-atomic.js';
+import { GitignoreMatcher } from './gitignore.js';
+/** Hard-excluded directories — never scanned regardless of .gitignore. */
+const ALWAYS_EXCLUDE = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    '.vexi',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    '.turbo',
+    '.cache',
+    'vendor',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.idea',
+    '.vscode',
+]);
+/** Ignore files larger than this (bytes) — configurable ceiling. */
+export const MAX_FILE_SIZE = 500 * 1024;
+/** Cap on files recorded in project.json (keeps prompts small). */
+const MAX_FILES = 400;
+/** Max directory depth to walk. */
+const MAX_DEPTH = 8;
+const EXT_LANGUAGES = {
+    '.ts': 'TypeScript',
+    '.tsx': 'TypeScript (React)',
+    '.js': 'JavaScript',
+    '.jsx': 'JavaScript (React)',
+    '.py': 'Python',
+    '.go': 'Go',
+    '.rs': 'Rust',
+    '.java': 'Java',
+    '.kt': 'Kotlin',
+    '.rb': 'Ruby',
+    '.php': 'PHP',
+    '.cs': 'C#',
+    '.cpp': 'C++',
+    '.c': 'C',
+    '.swift': 'Swift',
+    '.vue': 'Vue',
+    '.svelte': 'Svelte',
+    '.sql': 'SQL',
+    '.sh': 'Shell',
+    '.css': 'CSS',
+    '.scss': 'SCSS',
+    '.html': 'HTML',
+};
+/** npm dependency → human-readable stack entry. */
+const DEP_STACK = {
+    next: 'Next.js',
+    react: 'React',
+    vue: 'Vue',
+    svelte: 'Svelte',
+    '@angular/core': 'Angular',
+    express: 'Express',
+    fastify: 'Fastify',
+    hono: 'Hono',
+    nestjs: 'NestJS',
+    '@nestjs/core': 'NestJS',
+    prisma: 'Prisma',
+    '@prisma/client': 'Prisma',
+    mongoose: 'MongoDB (Mongoose)',
+    pg: 'PostgreSQL',
+    mysql2: 'MySQL',
+    sqlite3: 'SQLite',
+    'better-sqlite3': 'SQLite',
+    drizzle_orm: 'Drizzle ORM',
+    'drizzle-orm': 'Drizzle ORM',
+    tailwindcss: 'Tailwind CSS',
+    '@supabase/supabase-js': 'Supabase',
+    firebase: 'Firebase',
+    'next-auth': 'NextAuth',
+    '@auth/core': 'Auth.js',
+    passport: 'Passport',
+    jsonwebtoken: 'JWT',
+    stripe: 'Stripe',
+    vite: 'Vite',
+    webpack: 'Webpack',
+    electron: 'Electron',
+    'react-native': 'React Native',
+    jest: 'Jest',
+    vitest: 'Vitest',
+    typescript: 'TypeScript',
+    commander: 'CLI (commander)',
+};
+/** Filename/dependency evidence for architecture layers. */
+const LAYER_HINTS = [
+    { layer: 'frontend', test: (f) => /\.(tsx|jsx|vue|svelte|css|scss|html)$/.test(f) || /^(src\/)?(components|pages|app|views|public)\//.test(f) },
+    { layer: 'backend', test: (f) => /^(src\/)?(api|server|routes|controllers|services|middleware)\//.test(f) || /server\.(ts|js|py|go)$/.test(f) },
+    { layer: 'database', test: (f) => /(schema\.(prisma|sql)|migrations?\/|models?\/|\.sql$)/.test(f) },
+    { layer: 'auth', test: (f) => /(auth|login|session|jwt|oauth)/i.test(f) },
+    { layer: 'devops', test: (f) => /(dockerfile|docker-compose|\.github\/workflows|\.gitlab-ci|terraform|k8s|helm)/i.test(f) },
+    { layer: 'tests', test: (f) => /(\.(test|spec)\.|__tests__\/|^tests?\/)/.test(f) },
+];
+/** Scan the project rooted at `root` and cache the result. */
+export async function scanProject(root) {
+    const matcher = new GitignoreMatcher();
+    const gitignore = await fs.readFile(join(root, '.gitignore'), 'utf8').catch(() => '');
+    if (gitignore)
+        matcher.add(gitignore);
+    const files = [];
+    let truncated = false;
+    async function walk(dir, depth) {
+        if (depth > MAX_DEPTH || files.length >= MAX_FILES)
+            return;
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (files.length >= MAX_FILES) {
+                truncated = true;
+                return;
+            }
+            const abs = join(dir, entry.name);
+            const rel = relative(root, abs).replaceAll('\\', '/');
+            if (entry.isDirectory()) {
+                if (ALWAYS_EXCLUDE.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                if (matcher.ignores(rel, true))
+                    continue;
+                await walk(abs, depth + 1);
+            }
+            else if (entry.isFile()) {
+                if (matcher.ignores(rel, false))
+                    continue;
+                const stat = await fs.stat(abs).catch(() => null);
+                if (!stat || stat.size > MAX_FILE_SIZE)
+                    continue;
+                files.push(rel);
+            }
+        }
+    }
+    await walk(root, 0);
+    files.sort();
+    // ── Languages ──
+    const languages = {};
+    for (const file of files) {
+        const ext = file.slice(file.lastIndexOf('.'));
+        const lang = EXT_LANGUAGES[ext];
+        if (lang)
+            languages[lang] = (languages[lang] ?? 0) + 1;
+    }
+    // ── Stack (from package.json dependencies) ──
+    const stack = new Set();
+    const pkg = await readJson(join(root, 'package.json'));
+    if (pkg) {
+        for (const dep of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })) {
+            if (DEP_STACK[dep])
+                stack.add(DEP_STACK[dep]);
+        }
+    }
+    // Non-npm ecosystems
+    if (files.includes('requirements.txt') || files.includes('pyproject.toml'))
+        stack.add('Python');
+    if (files.includes('go.mod'))
+        stack.add('Go');
+    if (files.includes('Cargo.toml'))
+        stack.add('Rust');
+    if (files.includes('composer.json'))
+        stack.add('PHP');
+    // ── Architecture layers ──
+    const layers = {};
+    for (const { layer, test } of LAYER_HINTS) {
+        const evidence = files.filter(test).slice(0, 5);
+        if (evidence.length > 0)
+            layers[layer] = evidence;
+    }
+    const map = {
+        name: basename(root),
+        scannedAt: new Date().toISOString(),
+        fileCount: files.length,
+        truncated,
+        languages,
+        stack: [...stack],
+        layers,
+        files,
+    };
+    // Cache for other features (and future MCP resource) — best effort.
+    await writeJsonAtomic(join(root, '.vexi', 'project.json'), map).catch(() => { });
+    return map;
+}
+/**
+ * Render the project map as a compact text block for the system prompt.
+ * Kept deliberately small (~1-2KB) so it never floods the context window.
+ */
+export function projectSummary(map) {
+    const lines = [`Project: ${map.name} (${map.fileCount}${map.truncated ? '+' : ''} files)`];
+    const langs = Object.entries(map.languages)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([lang, n]) => `${lang} (${n})`);
+    if (langs.length)
+        lines.push(`Languages: ${langs.join(', ')}`);
+    if (map.stack.length)
+        lines.push(`Stack: ${map.stack.join(', ')}`);
+    for (const [layer, evidence] of Object.entries(map.layers)) {
+        lines.push(`${layer[0].toUpperCase() + layer.slice(1)}: ${evidence.join(', ')}`);
+    }
+    // Top-level structure only (max ~40 entries) — enough for orientation.
+    const topLevel = new Set();
+    for (const file of map.files) {
+        const slash = file.indexOf('/');
+        topLevel.add(slash === -1 ? file : file.slice(0, slash) + '/');
+        if (topLevel.size >= 40)
+            break;
+    }
+    lines.push(`Structure: ${[...topLevel].join(' ')}`);
+    return lines.join('\n');
+}

package/dist/skills/index.js

@@ -0,0 +1,121 @@
+/**
+ * Custom Skills system — Feature 2.5.
+ *
+ * Skills are plain markdown files in `.vexi/skills/` (per project). On
+ * session start every skill is read and injected into the system prompt,
+ * so generated code follows the user's own conventions, e.g.:
+ *
+ *   .vexi/skills/api-style.md    "All API endpoints follow REST + Zod validation"
+ *   .vexi/skills/arabic-docs.md  "All documentation written in Arabic"
+ *
+ * Skills can be added from local files or shared via GitHub URLs:
+ *   vexi skill add https://github.com/user/react-best-practices
+ */
+import { promises as fs } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+/** Max size of a single skill file (keeps the system prompt sane). */
+const MAX_SKILL_SIZE = 64 * 1024;
+function skillsDir(root) {
+    return join(root, '.vexi', 'skills');
+}
+/** Load all skills for a project (empty array when none exist). */
+export async function loadSkills(root) {
+    const dir = skillsDir(root);
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const content = await fs.readFile(join(dir, entry.name), 'utf8').catch(() => '');
+        if (content.trim()) {
+            skills.push({
+                name: entry.name.slice(0, -3),
+                content: content.slice(0, MAX_SKILL_SIZE).trim(),
+            });
+        }
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Render skills as a system-prompt block ('' when there are none). */
+export function skillsBlock(skills) {
+    if (skills.length === 0)
+        return '';
+    const parts = ['## User skills (project conventions you MUST follow)'];
+    for (const skill of skills) {
+        parts.push(`### ${skill.name}\n${skill.content}`);
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Add a skill from a local file path or a URL (GitHub URLs are converted
+ * to raw content automatically). Returns the saved skill name.
+ */
+export async function addSkill(root, source) {
+    let content;
+    let name;
+    if (/^https?:\/\//i.test(source)) {
+        const url = toRawUrl(source);
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new Error(`Could not fetch ${url} (HTTP ${res.status})`);
+        }
+        content = await res.text();
+        name = skillNameFromUrl(source);
+    }
+    else {
+        content = await fs.readFile(source, 'utf8');
+        name = basename(source, extname(source));
+    }
+    content = content.slice(0, MAX_SKILL_SIZE).trim();
+    if (!content)
+        throw new Error('Skill source is empty.');
+    name = sanitizeName(name);
+    const dir = skillsDir(root);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(join(dir, `${name}.md`), content + '\n', 'utf8');
+    return name;
+}
+/** Remove a skill by name. Returns true when a file was deleted. */
+export async function removeSkill(root, name) {
+    const file = join(skillsDir(root), `${sanitizeName(name)}.md`);
+    try {
+        await fs.unlink(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convert GitHub web URLs to raw-content URLs:
+ *   github.com/user/repo                    → raw .../main/README.md
+ *   github.com/user/repo/blob/branch/x.md   → raw .../branch/x.md
+ * Other URLs pass through unchanged.
+ */
+export function toRawUrl(url) {
+    const blob = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/(.+)$/i);
+    if (blob) {
+        return `https://raw.githubusercontent.com/${blob[1]}/${blob[2]}/${blob[3]}`;
+    }
+    const repo = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i);
+    if (repo) {
+        return `https://raw.githubusercontent.com/${repo[1]}/${repo[2]}/HEAD/README.md`;
+    }
+    return url;
+}
+/** Derive a skill name from a URL (last meaningful path segment). */
+function skillNameFromUrl(url) {
+    const segments = new URL(url).pathname.split('/').filter(Boolean);
+    let last = segments[segments.length - 1] ?? 'skill';
+    last = last.replace(/\.(md|markdown)$/i, '');
+    // For repo root URLs use the repo name, not "README"
+    if (/^readme$/i.test(last) && segments.length >= 2) {
+        last = segments[1].replace(/\.git$/i, '');
+    }
+    return last;
+}
+/** Keep skill file names safe and predictable. */
+function sanitizeName(name) {
+    const safe = name.replace(/[^a-z0-9_-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase();
+    return safe || 'skill';
+}

package/dist/ui/index.js

@@ -0,0 +1,39 @@
+/**
+ * Terminal UI helpers: Vexi branding, colors and status output.
+ * Palette: deep black background + electric blue (#2979FF) accent.
+ */
+import chalk from 'chalk';
+/** Vexi electric blue accent. */
+export const accent = chalk.hex('#2979FF');
+export const accentBold = chalk.hex('#2979FF').bold;
+export const dim = chalk.gray;
+export const ok = chalk.green;
+export const warn = chalk.yellow;
+export const err = chalk.red;
+const LOGO = `
+██╗   ██╗███████╗██╗  ██╗██╗
+██║   ██║██╔════╝╚██╗██╔╝██║
+██║   ██║█████╗   ╚███╔╝ ██║
+╚██╗ ██╔╝██╔══╝   ██╔██╗ ██║
+ ╚████╔╝ ███████╗██╔╝ ██╗██║
+  ╚═══╝  ╚══════╝╚═╝  ╚═╝╚═╝
+`;
+/** Print the Vexi ASCII banner. */
+export function printBanner(version) {
+    console.log(accentBold(LOGO));
+    console.log(dim(`  open-source AI coding agent · v${version}\n`));
+}
+/** Print the session status line: project, provider, model, language. */
+export function printStatusLine(info) {
+    const sep = dim(' · ');
+    console.log([
+        `${dim('project')} ${accent(info.project)}`,
+        `${dim('provider')} ${accent(info.provider)}`,
+        `${dim('model')} ${accent(info.model)}`,
+        `${dim('lang')} ${accent(info.lang)}`,
+    ].join(sep) + '\n');
+}
+/** Prompt label for user input. */
+export const userPrompt = accentBold('you ›');
+/** Label printed before the assistant's streamed reply. */
+export const vexiLabel = accentBold('vexi ›');

package/dist/utils/fs-atomic.js

@@ -0,0 +1,46 @@
+/**
+ * Shared async file helpers.
+ *
+ * All Vexi state files (.vexi/memory.json, .vexi/project.json,
+ * ~/.vexi/config.json) are written atomically: write to a temp file in the
+ * same directory, then rename. Rename is atomic on POSIX and effectively
+ * atomic on NTFS, which prevents corruption when the agent writes memory
+ * and session data concurrently.
+ */
+import { promises as fs } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+/** Read + parse a JSON file, returning `null` on any error. */
+export async function readJson(path) {
+    try {
+        return JSON.parse(await fs.readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomically write a JSON file (temp file + rename).
+ * Creates parent directories as needed. `mode` applies to the file
+ * (e.g. 0o600 for secrets); it is a no-op on Windows.
+ */
+export async function writeJsonAtomic(path, data, options = {}) {
+    const dir = dirname(path);
+    await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o755 });
+    const tmpPath = join(dir, `.${randomBytes(6).toString('hex')}.tmp`);
+    await fs.writeFile(tmpPath, JSON.stringify(data, null, 2) + '\n', {
+        encoding: 'utf8',
+        mode: options.mode ?? 0o644,
+    });
+    try {
+        await fs.rename(tmpPath, path);
+    }
+    catch (err) {
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+    if (options.mode !== undefined) {
+        // Re-assert permissions in case the file already existed (no-op on Windows).
+        await fs.chmod(path, options.mode).catch(() => { });
+    }
+}

package/dist/utils/open.js

@@ -0,0 +1,17 @@
+/**
+ * Open a file or URL with the OS default application (cross-platform).
+ */
+import { exec } from 'node:child_process';
+import { platform } from 'node:os';
+export function openInDefaultApp(path) {
+    const os = platform();
+    // Quote the path; on Windows `start` needs an empty title argument.
+    const cmd = os === 'win32'
+        ? `start "" "${path}"`
+        : os === 'darwin'
+            ? `open "${path}"`
+            : `xdg-open "${path}"`;
+    exec(cmd, () => {
+        // Best effort — if it fails the user still has the file path printed.
+    });
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "vexi-cli",
+  "version": "0.5.1",
+  "description": "Open-source AI coding agent for your terminal. Bring your own key, zero config, multilingual.",
+  "type": "module",
+  "bin": {
+    "vexi": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "coding-agent",
+    "terminal",
+    "assistant",
+    "byok",
+    "anthropic",
+    "openai",
+    "gemini",
+    "groq",
+    "openrouter",
+    "multilingual"
+  ],
+  "author": "Elomami1976",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Elomami1976/vexi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Elomami1976/vexi/issues"
+  },
+  "homepage": "https://github.com/Elomami1976/vexi#readme",
+  "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "ora": "^8.1.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}