gent-cli 7.0.0 → 9.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": "9.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/branch.js

@@ -148,6 +148,8 @@ async function syncBranchCreate(name, commitSha, gentPath) {
         // Non-fatal: branch created locally even if remote sync fails
         if (error.response?.status === 400) {
             console.log(chalk.gray(`  ⚠ Remote sync skipped (branch may already exist remotely)`));
+        } else if (error.response?.status === 403) {
+            console.log(chalk.yellow(`  ⚠ Remote sync skipped — no write access to this repository`));
         }
     }
 }
@@ -173,6 +175,8 @@ async function syncBranchDelete(name, gentPath) {
     } catch (error) {
         if (error.response?.status === 400) {
             console.log(chalk.gray(`  ⚠ Cannot delete default branch on remote`));
+        } else if (error.response?.status === 403) {
+            console.log(chalk.yellow(`  ⚠ Remote delete skipped — no write access to this repository`));
         } else if (error.response?.status === 404) {
             // Branch didn't exist remotely, that's fine
         }

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

@@ -11,15 +11,12 @@
  *   gent clone <url>                   → Clone into folder named after repo
  *   gent clone <url> <directory>       → Clone into specific directory
  *
- * ALGORITHM (client-side, no /clone/ endpoint):
+ * ALGORITHM:
  *   1. Parse URL to get owner_id + repo_name
- *   2. GET repo details → name, description, default_branch
- *   3. GET branches list → all branch names + SHAs
- *   4. GET commits list → all commits
- *   5. For each commit, fetch tree + blobs
- *   6. Create .gent/ directory structure
- *   7. Store all objects locally
- *   8. Checkout HEAD (restore working tree from latest commit)
+ *   2. GET /clone/ → full snapshot (commits, base64 objects, branches, tags)
+ *   3. Create .gent/ structure + store objects locally
+ *   4. Write commits.json / config / HEAD / staging
+ *   5. Checkout the default branch's tree
  *
  * ============================================================================
  */
@@ -32,7 +29,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 } = require('../utils/hash-engine');
 
 /**
  * Clone remote repository
@@ -65,14 +62,14 @@ async function clone(url, directory, options) {
             return;
         }
 
-        // 1. Get repo details
-        spinner.text = 'Fetching repository info...';
-        const repoDetail = await apiClient.get(
-            buildRepoUrl(API_ENDPOINTS.REPO_DETAIL, repoInfo)
+        // Fetch the full repository snapshot in one call.
+        spinner.text = 'Fetching repository...';
+        const payload = await apiClient.get(
+            buildRepoUrl(API_ENDPOINTS.REPO_CLONE, repoInfo)
         );
 
-        const repoName = repoDetail.name || repoInfo.repo_name;
-        const defaultBranch = repoDetail.default_branch || 'main';
+        const repoName = payload.name || repoInfo.repo_name;
+        const defaultBranch = payload.currentBranch || 'main';
         const targetDir = directory || repoName;
         const targetPath = path.resolve(process.cwd(), targetDir);
 
@@ -84,39 +81,6 @@ async function clone(url, directory, options) {
             }
         }
 
-        // 2. Get branches
-        spinner.text = 'Fetching branches...';
-        let remoteBranches = [];
-        try {
-            remoteBranches = await apiClient.get(
-                buildRepoUrl(API_ENDPOINTS.REPO_BRANCHES, repoInfo)
-            );
-        } catch {
-            // No branches yet
-        }
-
-        // 3. Get all commits
-        spinner.text = 'Fetching commits...';
-        let remoteCommits = [];
-        try {
-            remoteCommits = await apiClient.get(
-                buildRepoUrl(API_ENDPOINTS.REPO_COMMITS, repoInfo)
-            );
-        } catch {
-            // No commits yet
-        }
-
-        // 4. Get tags
-        spinner.text = 'Fetching tags...';
-        let remoteTags = [];
-        try {
-            remoteTags = await apiClient.get(
-                buildRepoUrl(API_ENDPOINTS.REPO_TAGS, repoInfo)
-            );
-        } catch {
-            // No tags
-        }
-
         // Create directory structure
         spinner.text = 'Setting up repository...';
         const gentPath = path.join(targetPath, GENT_DIR);
@@ -125,100 +89,33 @@ async function clone(url, directory, options) {
         await ensureDir(path.join(gentPath, 'refs', 'heads'));
         await ensureDir(path.join(gentPath, 'refs', 'tags'));
 
-        // 5. For each commit, fetch tree and blobs
-        const localCommits = [];
+        // Store blob objects (base64) into the local object store.
+        spinner.text = 'Storing objects...';
         let objectCount = 0;
-
-        for (let i = 0; i < remoteCommits.length; i++) {
-            const commit = remoteCommits[i];
-            spinner.text = `Fetching objects (${i + 1}/${remoteCommits.length})...`;
-
-            let treeEntries = [];
-            if (commit.tree_sha) {
-                try {
-                    const tree = await apiClient.get(
-                        buildRepoUrl(API_ENDPOINTS.REPO_TREE_DETAIL, { ...repoInfo, sha: commit.tree_sha })
-                    );
-                    treeEntries = tree.entries || [];
-                } catch {
-                    // Tree not available
-                }
-            }
-
-            // Fetch and store blobs
-            for (const entry of treeEntries) {
-                if (entry.type === 'blob' && entry.sha) {
-                    try {
-                        const blob = await apiClient.get(
-                            buildRepoUrl(API_ENDPOINTS.REPO_BLOB_DETAIL, { ...repoInfo, sha: entry.sha })
-                        );
-                        if (blob.content) {
-                            const buf = decodeRemoteBlobContent(blob.content, entry.sha);
-                            await storeBlob(gentPath, buf);
-                            objectCount++;
-                        }
-                    } catch {
-                        // Blob fetch failed
-                    }
-                }
-            }
-
-            // Convert to local commit format
-            localCommits.push({
-                hash: commit.sha,
-                message: commit.message,
-                author: { name: commit.author_name, email: commit.author_email },
-                timestamp: commit.committed_at,
-                parent: commit.parent_shas && commit.parent_shas[0] || null,
-                mergeParent: commit.parent_shas && commit.parent_shas[1] || null,
-                treeHash: commit.tree_sha,
-                tree: treeEntries.map(e => ({
-                    mode: e.mode || '100644',
-                    name: e.name,
-                    hash: e.sha,
-                    type: e.type || 'blob'
-                })),
-                files: treeEntries.map(e => ({ path: e.name, hash: e.sha })),
-                stats: {}
-            });
+        for (const obj of payload.objects || []) {
+            if (obj.type !== 'blob' || typeof obj.data !== 'string') continue;
+            await storeBlob(gentPath, Buffer.from(obj.data, 'base64'));
+            objectCount++;
         }
 
-        // Build branches map
-        const branches = {};
-        for (const b of remoteBranches) {
-            branches[b.name] = b.commit_sha;
-        }
-        if (!branches[defaultBranch]) {
-            branches[defaultBranch] = null;
-        }
-
-        // Build tags map
-        const tagsMap = {};
-        for (const t of remoteTags) {
-            tagsMap[t.name] = {
-                hash: t.commit_sha,
-                message: t.message || '',
-                annotated: t.annotated || false,
-                tagger: { name: t.tagger_name || '', email: t.tagger_email || '' },
-                timestamp: t.created_at
-            };
-        }
+        const localCommits = payload.commits || [];
+        const branches = payload.branches || {};
+        if (!(defaultBranch in branches)) branches[defaultBranch] = null;
 
         // Write commits.json
-        const repoData = {
+        await writeJSON(path.join(gentPath, COMMITS_FILE), {
             commits: localCommits,
             branches,
             currentBranch: defaultBranch,
-            tags: tagsMap
-        };
-        await writeJSON(path.join(gentPath, COMMITS_FILE), repoData);
+            tags: payload.tags || {}
+        });
 
         // Write config with remote
         const config = {
             user: { name: '', email: '' },
             repository: {
                 name: repoName,
-                description: repoDetail.description || '',
+                description: payload.description || '',
                 created: new Date().toISOString()
             },
             remotes: {
@@ -256,11 +153,17 @@ async function clone(url, directory, options) {
                 spinner.text = 'Checking out files...';
                 let fileCount = 0;
                 for (const entry of tree) {
+                    if (entry.type && entry.type !== 'blob') continue;
+                    const relPath = entry.name || entry.path;
+                    if (!relPath || !entry.hash) continue;
                     try {
-                        const content = await readBlobAsString(gentPath, entry.hash);
-                        const fullPath = path.join(targetPath, entry.name || entry.path);
+                        // 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, relPath);
                         await fs.mkdir(path.dirname(fullPath), { recursive: true });
-                        await fs.writeFile(fullPath, content, 'utf-8');
+                        await fs.writeFile(fullPath, buf);
                         fileCount++;
                     } catch {
                         // Blob missing
@@ -282,6 +185,8 @@ async function clone(url, directory, options) {
             console.error(chalk.red('Repository not found'));
         } else if (error.response?.status === 401) {
             console.error(chalk.red('Authentication failed — run "gent login"'));
+        } else if (error.response?.status === 403) {
+            console.error(chalk.red('Access denied — you do not have permission to clone this repository'));
         } else if (error.response?.data) {
             console.error(chalk.red(JSON.stringify(error.response.data)));
         } else {