gent-cli 7.0.0 → 8.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gent-cli",
-  "version": "7.0.0",
-  "description": "A modern, Git-like version control CLI with built-in cloud authentication and global user identity management.",
+  "version": "8.0.0",
+  "description": "A modern, Git-like version control CLI with cloud sync, AI-powered superpowers (ask/review/docs/changelog), and zero-friction setup (gent setup/doctor/config).",
   "main": "src/index.js",
   "bin": {
     "gent": "src/index.js"

package/src/commands/ai.js

@@ -0,0 +1,82 @@
+/**
+ * AI Command - Manage and verify AI integration.
+ *
+ *   gent ai status            → show key source, model, where it came from
+ *   gent ai test              → make a tiny live request to confirm it works
+ *   gent ai models            → list the model ids gent suggests
+ */
+
+const chalk = require('chalk');
+const ora = require('ora');
+const ai = require('../utils/ai-service');
+const userConfig = require('../utils/user-config');
+
+const SUGGESTED_MODELS = [
+    { id: 'claude-opus-4-7', tag: 'flagship', note: 'Highest quality' },
+    { id: 'claude-sonnet-4-6', tag: 'balanced', note: 'Strong, faster, cheaper' },
+    { id: 'claude-haiku-4-5', tag: 'fastest', note: 'Fastest & cheapest' },
+];
+
+async function aiCommand(subcommand) {
+    const sub = (subcommand || 'status').toLowerCase();
+    switch (sub) {
+        case 'status': return status();
+        case 'test': return test();
+        case 'models': return models();
+        default:
+            console.error(chalk.red(`Unknown subcommand '${sub}'`));
+            console.log(chalk.gray('Usage: gent ai <status|test|models>'));
+            process.exit(1);
+    }
+}
+
+async function status() {
+    const { value: key, source: keySource } = await ai.resolveKey();
+    const model = await ai.resolveModel();
+    const { source: modelSource } = await userConfig.getResolved('ai.model');
+
+    console.log(chalk.bold.cyan('\nGent AI status\n'));
+    if (key) {
+        console.log(`  ${chalk.green('●')} API key:   ${userConfig.maskSecret(key)}  ${chalk.gray(`[${keySource}]`)}`);
+    } else {
+        console.log(`  ${chalk.gray('○')} API key:   ${chalk.gray('not set')}`);
+        console.log(chalk.gray('             ↳ ' + ai.disabledHint()));
+    }
+    console.log(`  ${chalk.green('●')} Model:     ${model}  ${chalk.gray(`[${modelSource}]`)}`);
+    console.log(chalk.gray('\n  Run `gent ai test` to verify the key actually works.'));
+    console.log();
+}
+
+async function test() {
+    const { value: key } = await ai.resolveKey();
+    if (!key) {
+        console.error(chalk.red('No AI key configured.'));
+        console.log(chalk.yellow('Set one with `gent config set ai.api_key <key>`.'));
+        process.exit(1);
+    }
+
+    const model = await ai.resolveModel();
+    const spinner = ora(`Pinging Anthropic (${model})...`).start();
+    try {
+        const reply = await ai.complete({
+            prompt: 'Reply with the single word: pong',
+            maxTokens: 8,
+        });
+        spinner.succeed(chalk.green(`✓ Reachable. Reply: "${reply}"`));
+    } catch (err) {
+        spinner.fail(chalk.red(err.message));
+        process.exit(1);
+    }
+}
+
+async function models() {
+    const current = await ai.resolveModel();
+    console.log(chalk.bold.cyan('\nSuggested Claude models\n'));
+    for (const m of SUGGESTED_MODELS) {
+        const active = m.id === current ? chalk.green(' (current)') : '';
+        console.log(`  ${chalk.cyan(m.id.padEnd(22))} ${chalk.gray(m.tag.padEnd(10))} ${m.note}${active}`);
+    }
+    console.log(chalk.gray('\n  Switch with: gent config set ai.model <id>\n'));
+}
+
+module.exports = aiCommand;

package/src/commands/ask.js

@@ -0,0 +1,121 @@
+/**
+ * Ask Command - Plain-English Q&A about the current repo.
+ *
+ *   gent ask "what does this project do?"
+ *   gent ask "who has touched src/server.js recently?"
+ *   gent ask "what's pending on the current branch?"
+ *
+ * Builds a compact repo summary (README + last N commits + tree listing) and
+ * sends it as context. Falls back to a useful text dump if no AI key is set.
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { getGentPath, readJSON, pathExists } = require('../utils/fileSystem');
+const fs = require('fs').promises;
+const { COMMITS_FILE, CONFIG_FILE } = require('../utils/constants');
+const ai = require('../utils/ai-service');
+
+const MAX_CONTEXT_CHARS = 14000;
+const MAX_COMMITS = 25;
+
+async function ask(question, options = {}) {
+    try {
+        if (!question || !question.trim()) {
+            console.error(chalk.red('Usage: gent ask "<your question>"'));
+            process.exit(1);
+        }
+
+        const gentPath = await getGentPath();
+        const context = await buildRepoContext(gentPath);
+
+        if (!ai.isEnabled()) {
+            console.log(chalk.yellow(ai.disabledHint()));
+            console.log(chalk.gray('\nHere is the raw repo context you can pipe into another tool:\n'));
+            console.log(context);
+            return;
+        }
+
+        const spinner = ora(`Asking ${ai.getModel()}...`).start();
+        try {
+            const answer = await ai.complete({
+                system:
+                    'You are a senior engineer answering questions about a software repository. ' +
+                    'Be concrete and concise. If the answer is not in the context, say so. ' +
+                    'Reference filenames and short commit hashes when helpful.',
+                prompt: `Repository context:\n\n${context}\n\nQuestion: ${question}`,
+                maxTokens: 1024,
+            });
+            spinner.stop();
+            console.log('\n' + answer + '\n');
+        } catch (err) {
+            spinner.fail(chalk.red(err.message));
+            process.exit(1);
+        }
+    } catch (error) {
+        if (error.code === 'ENOENT' && error.message.includes('.gent')) {
+            console.error(chalk.red('Error: Not a gent repository'));
+            console.log(chalk.yellow('Run "gent init" to initialize a repository'));
+        } else {
+            console.error(chalk.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+async function buildRepoContext(gentPath) {
+    const cwd = process.cwd();
+    const parts = [];
+
+    // Project name + description from config
+    try {
+        const config = await readJSON(path.join(gentPath, CONFIG_FILE));
+        const repo = config.repository || {};
+        parts.push(`# Project\nname: ${repo.name || '(unnamed)'}\ndescription: ${repo.description || ''}`);
+    } catch { /* missing config — fine */ }
+
+    // README if present (any case, common extensions)
+    const readme = await findReadme(cwd);
+    if (readme) {
+        const text = await fs.readFile(readme.path, 'utf-8').catch(() => '');
+        if (text) parts.push(`# README (${readme.rel})\n${text.slice(0, 4000)}`);
+    }
+
+    // Recent commits
+    try {
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const commits = (repository.commits || []).slice(-MAX_COMMITS).reverse();
+        const branch = repository.currentBranch || 'main';
+        const lines = commits.map(c =>
+            `- ${(c.hash || '').slice(0, 7)} (${(c.author?.name || 'unknown')}): ${(c.message || '').split('\n')[0]}`
+        );
+        parts.push(`# Recent commits on '${branch}'\n${lines.join('\n')}`);
+    } catch { /* no commits yet — fine */ }
+
+    // Top-level layout
+    try {
+        const entries = await fs.readdir(cwd, { withFileTypes: true });
+        const layout = entries
+            .filter(e => !e.name.startsWith('.') && e.name !== 'node_modules')
+            .map(e => e.isDirectory() ? `${e.name}/` : e.name)
+            .slice(0, 60);
+        parts.push(`# Top-level layout\n${layout.join('\n')}`);
+    } catch { /* unreadable — fine */ }
+
+    const joined = parts.join('\n\n');
+    return joined.length > MAX_CONTEXT_CHARS
+        ? joined.slice(0, MAX_CONTEXT_CHARS) + '\n... (context truncated)'
+        : joined;
+}
+
+async function findReadme(cwd) {
+    const candidates = ['README.md', 'readme.md', 'README.txt', 'README', 'README.rst'];
+    for (const c of candidates) {
+        const p = path.join(cwd, c);
+        if (await pathExists(p)) return { path: p, rel: c };
+    }
+    return null;
+}
+
+module.exports = ask;

package/src/commands/changelog.js

@@ -0,0 +1,121 @@
+/**
+ * Changelog Command - AI-grouped changelog between two refs.
+ *
+ *   gent changelog                 → since the most recent tag (or last 50 commits)
+ *   gent changelog <from>..<to>    → commits between two refs
+ *   gent changelog <from>          → from <from> to HEAD
+ *   gent changelog --plain         → flat list, no AI grouping
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const { getGentPath, readJSON } = require('../utils/fileSystem');
+const { COMMITS_FILE } = require('../utils/constants');
+const ai = require('../utils/ai-service');
+
+const MAX_COMMITS = 200;
+
+async function changelog(range, options = {}) {
+    try {
+        const gentPath = await getGentPath();
+        const repository = await readJSON(path.join(gentPath, COMMITS_FILE));
+        const commits = repository.commits || [];
+        if (commits.length === 0) {
+            console.log(chalk.yellow('No commits yet.'));
+            return;
+        }
+
+        const { from, to } = resolveRange(range, repository);
+        const selected = commitsBetween(commits, from, to);
+
+        if (selected.length === 0) {
+            console.log(chalk.yellow('No commits in the requested range.'));
+            return;
+        }
+
+        const header = `${chalk.bold.cyan('Changelog')}  ${chalk.gray(
+            `${(from || 'root').slice(0, 7)}..${(to || 'HEAD').slice(0, 7)}  ` +
+            `(${selected.length} commits)`
+        )}`;
+        console.log('\n' + header + '\n');
+
+        if (options.plain || !ai.isEnabled()) {
+            for (const c of selected) {
+                const short = (c.hash || '').slice(0, 7);
+                const subject = (c.message || '').split('\n')[0];
+                console.log(`  ${chalk.gray(short)} ${subject}`);
+            }
+            if (!ai.isEnabled()) {
+                console.log(chalk.gray(`\n${ai.disabledHint()}`));
+            }
+            return;
+        }
+
+        const summary = selected.map(c =>
+            `- ${(c.hash || '').slice(0, 7)}: ${(c.message || '').split('\n')[0]}`
+        ).join('\n');
+
+        const spinner = ora(`Grouping with ${ai.getModel()}...`).start();
+        try {
+            const out = await ai.complete({
+                system:
+                    'You write release-note-style changelogs. Group commits into ' +
+                    'Features / Fixes / Improvements / Other. Keep each bullet to one line ' +
+                    'and start with a verb. Drop merge commits and noise. Reply with Markdown.',
+                prompt: `Commits (newest first):\n\n${summary}`,
+                maxTokens: 1500,
+            });
+            spinner.stop();
+            console.log(out + '\n');
+        } catch (err) {
+            spinner.fail(chalk.yellow('AI grouping failed — falling back to plain list'));
+            console.log(chalk.gray(`(${err.message})\n`));
+            for (const c of selected) {
+                console.log(`  ${chalk.gray((c.hash || '').slice(0, 7))} ${(c.message || '').split('\n')[0]}`);
+            }
+        }
+    } catch (error) {
+        if (error.code === 'ENOENT' && error.message.includes('.gent')) {
+            console.error(chalk.red('Error: Not a gent repository'));
+        } else {
+            console.error(chalk.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+function resolveRange(range, repository) {
+    const head = repository.branches[repository.currentBranch] || null;
+    if (!range) {
+        // Use most recent tag if any, else null (means "all up to MAX_COMMITS")
+        const tags = repository.tags || {};
+        const tagHashes = Object.values(tags).map(t => t.hash || t.commit_sha).filter(Boolean);
+        return { from: tagHashes[tagHashes.length - 1] || null, to: head };
+    }
+    if (range.includes('..')) {
+        const [from, to] = range.split('..');
+        return { from: from || null, to: to || head };
+    }
+    return { from: range, to: head };
+}
+
+function commitsBetween(commits, from, to) {
+    const byHash = new Map(commits.map(c => [c.hash, c]));
+    const startHash = to || (commits[commits.length - 1] || {}).hash;
+    if (!startHash) return [];
+
+    const result = [];
+    let cur = startHash;
+    const seen = new Set();
+    while (cur && cur !== from && !seen.has(cur) && result.length < MAX_COMMITS) {
+        const c = byHash.get(cur);
+        if (!c) break;
+        seen.add(cur);
+        result.push(c);
+        cur = c.parent;
+    }
+    return result; // newest first
+}
+
+module.exports = changelog;

package/src/commands/clone.js

@@ -32,7 +32,7 @@ const { ensureDir, writeJSON, pathExists } = require('../utils/fileSystem');
 const { GENT_DIR, CONFIG_FILE, STAGING_FILE, COMMITS_FILE, API_ENDPOINTS, buildRepoUrl, parseRemoteUrl } = require('../utils/constants');
 const apiClient = require('../utils/api-client');
 const authStorage = require('../utils/auth-storage');
-const { storeBlob, readBlobAsString, decodeRemoteBlobContent } = require('../utils/hash-engine');
+const { storeBlob, readBlob, decodeRemoteBlobContent } = require('../utils/hash-engine');
 
 /**
  * Clone remote repository
@@ -257,10 +257,13 @@ async function clone(url, directory, options) {
                 let fileCount = 0;
                 for (const entry of tree) {
                     try {
-                        const content = await readBlobAsString(gentPath, entry.hash);
+                        // Write the raw Buffer — not a UTF-8 string. Decoding a
+                        // binary blob (PNG, PDF, etc.) as UTF-8 would replace
+                        // non-utf-8 bytes with U+FFFD, silently corrupting it.
+                        const buf = await readBlob(gentPath, entry.hash);
                         const fullPath = path.join(targetPath, entry.name || entry.path);
                         await fs.mkdir(path.dirname(fullPath), { recursive: true });
-                        await fs.writeFile(fullPath, content, 'utf-8');
+                        await fs.writeFile(fullPath, buf);
                         fileCount++;
                     } catch {
                         // Blob missing

package/src/commands/config.js

@@ -0,0 +1,147 @@
+/**
+ * Config Command - Manage CLI-wide settings (~/.gent/cli-config.json)
+ *
+ *   gent config list                      → show all settings + source
+ *   gent config get <key>                 → print one setting
+ *   gent config set <key> <value>         → save a setting
+ *   gent config unset <key>               → remove a setting
+ *   gent config path                      → print config file location
+ *
+ *   gent config set ai.api_key <key>      ← stored obfuscated
+ *   gent config set api.base_url http://localhost:8000
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const userConfig = require('../utils/user-config');
+
+async function config(subcommand, args, options) {
+    try {
+        const sub = (subcommand || 'list').toLowerCase();
+        const positional = args || [];
+
+        switch (sub) {
+            case 'list':
+            case 'ls':
+                return list();
+            case 'get':
+                return get(positional[0]);
+            case 'set':
+                return set(positional[0], positional[1], options);
+            case 'unset':
+            case 'remove':
+            case 'rm':
+                return unset(positional[0]);
+            case 'path':
+                console.log(userConfig.getConfigPath());
+                return;
+            default:
+                console.error(chalk.red(`Unknown subcommand '${sub}'`));
+                console.log(chalk.gray('Usage: gent config <list|get|set|unset|path> [args]'));
+                process.exit(1);
+        }
+    } catch (error) {
+        console.error(chalk.red('Error:'), error.message);
+        process.exit(1);
+    }
+}
+
+async function list() {
+    const rows = await userConfig.listAll();
+    console.log(chalk.bold.cyan('\nGent CLI configuration\n'));
+
+    const sourceColor = {
+        env: chalk.magenta,
+        config: chalk.green,
+        default: chalk.gray,
+        unset: chalk.gray,
+    };
+
+    for (const row of rows) {
+        const value = row.value === undefined
+            ? chalk.gray('(not set)')
+            : chalk.white(row.value);
+        const sourceLabel = row.source === 'env'
+            ? `env: ${row.envName}`
+            : row.source;
+        console.log(
+            `  ${chalk.cyan(row.key.padEnd(16))} ${value}  ` +
+            sourceColor[row.source](`[${sourceLabel}]`)
+        );
+    }
+    console.log(chalk.gray(`\nFile: ${userConfig.getConfigPath()}`));
+    console.log(chalk.gray('Set a value: gent config set <key> <value>\n'));
+}
+
+async function get(key) {
+    if (!key) {
+        console.error(chalk.red('Usage: gent config get <key>'));
+        process.exit(1);
+    }
+    if (!userConfig.isAllowedKey(key)) {
+        console.error(chalk.red(`Unknown key '${key}'`));
+        console.log(chalk.gray(`Allowed: ${userConfig.listAllowedKeys().join(', ')}`));
+        process.exit(1);
+    }
+    const resolved = await userConfig.getResolved(key);
+    if (resolved.value === undefined) {
+        console.log(chalk.gray('(not set)'));
+        return;
+    }
+    console.log(resolved.value);
+}
+
+async function set(key, value, options) {
+    if (!key) {
+        console.error(chalk.red('Usage: gent config set <key> <value>'));
+        process.exit(1);
+    }
+    if (!userConfig.isAllowedKey(key)) {
+        console.error(chalk.red(`Unknown key '${key}'`));
+        console.log(chalk.gray(`Allowed: ${userConfig.listAllowedKeys().join(', ')}`));
+        process.exit(1);
+    }
+
+    // Secret prompt: if no value given for ai.api_key, prompt with masking.
+    if ((value === undefined || value === '') && key === 'ai.api_key') {
+        const answers = await inquirer.prompt([{
+            type: 'password',
+            name: 'value',
+            message: 'Anthropic API key:',
+            mask: '*',
+            validate: (input) => input.length > 0 || 'Key cannot be empty',
+        }]);
+        value = answers.value;
+    }
+
+    if (value === undefined) {
+        console.error(chalk.red('Usage: gent config set <key> <value>'));
+        process.exit(1);
+    }
+
+    await userConfig.set(key, value);
+    const display = key === 'ai.api_key' ? userConfig.maskSecret(value) : value;
+    console.log(chalk.green(`✓ ${key} = ${display}`));
+
+    const envName = userConfig.ENV_OVERRIDES[key];
+    if (envName && process.env[envName]) {
+        console.log(chalk.yellow(
+            `Note: ${envName} is currently set in your environment and will override this value.`
+        ));
+    }
+}
+
+async function unset(key) {
+    if (!key) {
+        console.error(chalk.red('Usage: gent config unset <key>'));
+        process.exit(1);
+    }
+    if (!userConfig.isAllowedKey(key)) {
+        console.error(chalk.red(`Unknown key '${key}'`));
+        process.exit(1);
+    }
+    await userConfig.unset(key);
+    console.log(chalk.green(`✓ Removed ${key}`));
+}
+
+module.exports = config;

package/src/commands/docs.js

@@ -0,0 +1,141 @@
+/**
+ * Docs Command - AI-generate a README for the current repo.
+ *
+ *   gent docs                  → print suggested README to stdout
+ *   gent docs --write          → write to README.md (prompt before overwrite)
+ *   gent docs --section <name> → only regenerate a section (Usage, Install, ...)
+ *
+ * Builds context from: repository name/desc, file tree, key files (package.json,
+ * pyproject.toml, etc.), and a sample of source files.
+ */
+
+const path = require('path');
+const fs = require('fs').promises;
+const chalk = require('chalk');
+const ora = require('ora');
+const inquirer = require('inquirer');
+const { getGentPath, readJSON, pathExists } = require('../utils/fileSystem');
+const { CONFIG_FILE } = require('../utils/constants');
+const ai = require('../utils/ai-service');
+
+const KEY_FILES = [
+    'package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod',
+    'requirements.txt', 'Gemfile', 'composer.json', 'pom.xml',
+];
+
+const MAX_CONTEXT_CHARS = 16000;
+
+async function docs(options = {}) {
+    try {
+        const cwd = process.cwd();
+        const gentPath = await getGentPath();
+
+        if (!ai.isEnabled()) {
+            console.error(chalk.red('AI is required for `gent docs`.'));
+            console.log(chalk.yellow(ai.disabledHint()));
+            process.exit(1);
+        }
+
+        const context = await buildDocsContext(gentPath, cwd);
+        const target = options.section
+            ? `Generate ONLY the "${options.section}" section of a README.md.`
+            : 'Generate a complete, polished README.md.';
+
+        const spinner = ora(`Drafting README with ${ai.getModel()}...`).start();
+        let draft;
+        try {
+            draft = await ai.complete({
+                system:
+                    'You write clear, accurate, well-formatted README.md files. ' +
+                    'Use plain GitHub-flavored Markdown. Do not invent features that are not ' +
+                    'in the provided context. Prefer short paragraphs and concrete examples.',
+                prompt:
+                    `${target}\n\nProject context:\n\n${context}\n\n` +
+                    'Output: ONLY the Markdown. No preamble, no code fences around the whole document.',
+                maxTokens: 2500,
+            });
+        } catch (err) {
+            spinner.fail(chalk.red(err.message));
+            process.exit(1);
+        }
+        spinner.stop();
+
+        if (!options.write) {
+            console.log(draft);
+            console.log(chalk.gray('\n(use --write to save to README.md)\n'));
+            return;
+        }
+
+        const target_path = path.join(cwd, 'README.md');
+        if (await pathExists(target_path)) {
+            const { ok } = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'ok',
+                message: `Overwrite existing README.md?`,
+                default: false,
+            }]);
+            if (!ok) {
+                console.log(chalk.yellow('Aborted — nothing written.'));
+                return;
+            }
+        }
+        await fs.writeFile(target_path, draft + '\n', 'utf-8');
+        console.log(chalk.green(`✓ Wrote ${path.relative(cwd, target_path)}`));
+    } catch (error) {
+        if (error.code === 'ENOENT' && error.message.includes('.gent')) {
+            console.error(chalk.red('Error: Not a gent repository'));
+        } else {
+            console.error(chalk.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}
+
+async function buildDocsContext(gentPath, cwd) {
+    const parts = [];
+
+    try {
+        const config = await readJSON(path.join(gentPath, CONFIG_FILE));
+        const r = config.repository || {};
+        parts.push(`# Project metadata\nname: ${r.name || ''}\ndescription: ${r.description || ''}`);
+    } catch { /* fine */ }
+
+    // Top-level layout
+    try {
+        const entries = await fs.readdir(cwd, { withFileTypes: true });
+        const layout = entries
+            .filter(e => !e.name.startsWith('.') && e.name !== 'node_modules')
+            .map(e => e.isDirectory() ? `${e.name}/` : e.name);
+        parts.push(`# Top-level layout\n${layout.join('\n')}`);
+    } catch { /* fine */ }
+
+    // Key manifest files
+    for (const f of KEY_FILES) {
+        const p = path.join(cwd, f);
+        if (await pathExists(p)) {
+            try {
+                const text = await fs.readFile(p, 'utf-8');
+                parts.push(`# ${f}\n${text.slice(0, 2000)}`);
+            } catch { /* fine */ }
+        }
+    }
+
+    // Existing README (so the model can preserve voice if user wants to refresh)
+    for (const c of ['README.md', 'readme.md']) {
+        const p = path.join(cwd, c);
+        if (await pathExists(p)) {
+            try {
+                const text = await fs.readFile(p, 'utf-8');
+                parts.push(`# Existing ${c}\n${text.slice(0, 3000)}`);
+                break;
+            } catch { /* fine */ }
+        }
+    }
+
+    const joined = parts.join('\n\n');
+    return joined.length > MAX_CONTEXT_CHARS
+        ? joined.slice(0, MAX_CONTEXT_CHARS) + '\n... (context truncated)'
+        : joined;
+}
+
+module.exports = docs;