gent-cli 6.0.1 → 8.0.0

package/src/commands/web.js

@@ -0,0 +1,72 @@
+/**
+ * Web Command - Open the current repo (or a specific commit/branch) in browser.
+ *
+ *   gent web                       → open repo page
+ *   gent web --branch <name>       → open a specific branch
+ *   gent web --commit <hash>       → open a specific commit
+ *   gent web --print               → don't launch, just print the URL
+ *
+ * Builds the URL from the configured api.base_url and the remote's owner_id/repo_name.
+ */
+
+const path = require('path');
+const { exec } = require('child_process');
+const chalk = require('chalk');
+const { getGentPath, readJSON } = require('../utils/fileSystem');
+const { CONFIG_FILE, parseRemoteUrl } = require('../utils/constants');
+const userConfig = require('../utils/user-config');
+
+async function web(options = {}) {
+    try {
+        const gentPath = await getGentPath();
+        const config = await readJSON(path.join(gentPath, CONFIG_FILE));
+        const remote = (config.remotes || {}).origin;
+        if (!remote) {
+            console.error(chalk.red('No origin remote configured.'));
+            console.log(chalk.yellow('Run `gent remote add origin <url>` or `gent init --remote`.'));
+            process.exit(1);
+        }
+        const info = parseRemoteUrl(remote.url);
+        if (!info) {
+            console.error(chalk.red(`Origin URL '${remote.url}' isn't a recognized gent URL.`));
+            process.exit(1);
+        }
+
+        const { value: baseUrl } = await userConfig.getResolved('api.base_url');
+        // Strip /api suffix if present so we get the web host
+        const webHost = baseUrl.replace(/\/api\/?$/, '').replace(/\/$/, '');
+
+        let url = `${webHost}/${info.owner_id}/${info.repo_name}`;
+        if (options.branch) url += `/tree/${encodeURIComponent(options.branch)}`;
+        if (options.commit) url += `/commit/${encodeURIComponent(options.commit)}`;
+
+        if (options.print) {
+            console.log(url);
+            return;
+        }
+
+        console.log(chalk.gray(`Opening ${url}`));
+        openInBrowser(url);
+    } 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 openInBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open'
+        : process.platform === 'win32' ? 'start ""'
+        : 'xdg-open';
+    exec(`${cmd} "${url}"`, (err) => {
+        if (err) {
+            console.error(chalk.yellow('Could not auto-open. URL:'));
+            console.log(url);
+        }
+    });
+}
+
+module.exports = web;

package/src/index.js

@@ -7,17 +7,25 @@
  * ============================================================================
  *
  * COMMANDS:
+ *   Setup:       setup, config, doctor
  *   Repository:  init, clone
  *   Staging:     add, rm, reset, status, diff
- *   History:     commit, log, show, tag
- *   Branching:   branch, checkout, merge, stash
- *   Remote:      remote, push, pull
+ *   History:     commit, log, show, tag, explain
+ *   Branching:   branch, checkout, merge, resolve, stash
+ *   Safety:      undo, redo
+ *   Insight:     summary, ask, review, docs, changelog
+ *   Remote:      remote, repos, push, pull, search, web, share
  *   Auth:        register, login, logout, whoami
+ *   AI:          ai (status|test|models)
+ *   Templates:   template (list|use)
  *
  * @author Abdalrahman Kanawati
- * @version 2.0.0
+ * @version 7.0.0
  */
 
+// Boot: load env files BEFORE anything else reads process.env.
+require('./utils/env-loader').load();
+
 const { program } = require('commander');
 const chalk = require('chalk');
 const packageJson = require('../package.json');
@@ -42,6 +50,10 @@ const remoteCommand = require('./commands/remote');
 const pushCommand = require('./commands/push');
 const pullCommand = require('./commands/pull');
 const reposCommand = require('./commands/repos');
+const undoCommand = require('./commands/undo');
+const resolveCommand = require('./commands/resolve');
+const summaryCommand = require('./commands/summary');
+const explainCommand = require('./commands/explain');
 
 // Import auth commands
 const registerCommand = require('./commands/register');
@@ -49,6 +61,20 @@ const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
 const whoamiCommand = require('./commands/whoami');
 
+// Import new gent-platform commands
+const configCommand = require('./commands/config');
+const doctorCommand = require('./commands/doctor');
+const setupCommand = require('./commands/setup');
+const aiCommand = require('./commands/ai');
+const askCommand = require('./commands/ask');
+const reviewCommand = require('./commands/review');
+const docsCommand = require('./commands/docs');
+const changelogCommand = require('./commands/changelog');
+const webCommand = require('./commands/web');
+const shareCommand = require('./commands/share');
+const searchCommand = require('./commands/search');
+const templateCommand = require('./commands/template');
+
 // Configure CLI
 program
     .name('gent')
@@ -78,10 +104,16 @@ program
     .action(statusCommand);
 
 program
-    .command('add <files...>')
-    .description('Add file contents to the staging area')
+    .command('add [files...]')
+    .description('Add file contents to the staging area (use -A/--all to add everything)')
     .option('-A, --all', 'Add all files')
-    .action(addCommand);
+    .action((files, options) => {
+        if ((!files || files.length === 0) && !options.all) {
+            console.error('error: specify files to add, or use -A to add all');
+            process.exit(1);
+        }
+        return addCommand(files || [], options);
+    });
 
 program
     .command('rm <files...>')
@@ -110,6 +142,7 @@ program
     .description('Record changes to the repository')
     .option('-m, --message <message>', 'Commit message')
     .option('-a, --all', 'Automatically stage all modified files')
+    .option('--ai', 'Suggest a commit message with AI (needs ANTHROPIC_API_KEY)')
     .action(commitCommand);
 
 program
@@ -117,6 +150,7 @@ program
     .description('Show commit logs')
     .option('-n, --number <count>', 'Limit the number of commits to show', '10')
     .option('--oneline', 'Show each commit on a single line')
+    .option('--graph', 'Show an ASCII commit graph with branches and merges')
     .option('--stat', 'Show file change statistics')
     .action(logCommand);
 
@@ -133,6 +167,18 @@ program
     .option('-d, --delete <name>', 'Delete a tag')
     .action(tagCommand);
 
+program
+    .command('explain [ref]')
+    .description('Explain a commit or staged changes in plain language')
+    .option('--staged', 'Explain staged changes instead of a commit')
+    .action(explainCommand);
+
+program
+    .command('summary')
+    .description('Show a repository health & statistics dashboard')
+    .option('--ai', 'Add an AI-written health narrative (needs ANTHROPIC_API_KEY)')
+    .action(summaryCommand);
+
 // ─── Branching & Merging ────────────────────────────────
 
 program
@@ -155,6 +201,11 @@ program
     .option('-m, --message <message>', 'Merge commit message')
     .action(mergeCommand);
 
+program
+    .command('resolve')
+    .description('Interactively resolve merge conflicts left by "gent merge"')
+    .action(resolveCommand);
+
 program
     .command('stash [subcommand]')
     .description('Stash working tree changes (pop|list|drop|apply)')
@@ -162,6 +213,17 @@ program
     .option('-i, --index <index>', 'Stash index for pop/apply/drop')
     .action(stashCommand);
 
+program
+    .command('undo')
+    .description('Reverse the last history-changing operation (safety net)')
+    .option('-l, --list', 'Show the operation history')
+    .action(undoCommand);
+
+program
+    .command('redo')
+    .description('Re-apply the last undone operation')
+    .action(undoCommand.redo);
+
 // ─── Remote & Sync ──────────────────────────────────────
 
 program
@@ -190,6 +252,83 @@ program
     .description('Pull and merge remote commits')
     .action(pullCommand);
 
+// ─── Setup, Config & Diagnostics ────────────────────────
+
+program
+    .command('setup')
+    .description('Interactive first-run wizard (backend URL, login, AI key, identity)')
+    .action(setupCommand);
+
+program
+    .command('config [subcommand] [args...]')
+    .description('Manage CLI settings (list|get|set|unset|path) — e.g. gent config set ai.api_key <key>')
+    .action(configCommand);
+
+program
+    .command('doctor')
+    .description('Run a health check across node, repo, auth, backend, and AI key')
+    .option('--ai', 'Also live-test the AI key with a tiny request')
+    .action(doctorCommand);
+
+program
+    .command('ai [subcommand]')
+    .description('Inspect AI integration (status|test|models)')
+    .action(aiCommand);
+
+// ─── Platform-special (AI-powered) ──────────────────────
+
+program
+    .command('ask <question>')
+    .description('Ask Claude a question about this repo (needs AI key)')
+    .action(askCommand);
+
+program
+    .command('review [ref]')
+    .description('AI code review on staged changes (default), HEAD, or a specific commit')
+    .option('--staged', 'Force review of staged changes')
+    .option('--head', 'Force review of HEAD commit')
+    .action(reviewCommand);
+
+program
+    .command('docs')
+    .description('Generate a README.md draft for this repo using AI')
+    .option('--write', 'Write the draft to README.md instead of stdout')
+    .option('--section <name>', 'Only generate a single named section')
+    .action(docsCommand);
+
+program
+    .command('changelog [range]')
+    .description('Print a changelog. range = <from>..<to> or <from> (default: since last tag)')
+    .option('--plain', 'Skip AI grouping — flat commit list')
+    .action(changelogCommand);
+
+program
+    .command('web')
+    .description('Open the current repo (or a branch/commit) on the gent web app')
+    .option('--branch <name>', 'Open a specific branch')
+    .option('--commit <hash>', 'Open a specific commit')
+    .option('--print', 'Print the URL instead of launching a browser')
+    .action(webCommand);
+
+program
+    .command('share')
+    .description('Print a shareable link to current branch tip (or --branch/--commit)')
+    .option('--branch <name>', 'Link to a specific branch')
+    .option('--commit <hash>', 'Link to a specific commit')
+    .action(shareCommand);
+
+program
+    .command('search [query]')
+    .description('Search your repositories on the gent backend')
+    .option('--mine', 'Only repos you own')
+    .option('--json', 'Output as JSON')
+    .action(searchCommand);
+
+program
+    .command('template [subcommand] [args...]')
+    .description('Quick-start from a baked-in template (list|use <name> [directory])')
+    .action(templateCommand);
+
 // ─── Authentication ─────────────────────────────────────
 
 program
@@ -231,19 +370,57 @@ program
         }
     });
 
+// Friendlier global error mapping. Per-command handlers still own their own
+// errors; this catches anything that bubbles up (e.g. unknown command).
+function explainError(err) {
+    if (!err) return '';
+    if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND') {
+        return `Cannot reach the gent backend. Check the URL with \`gent config get api.base_url\` and try \`gent doctor\`.`;
+    }
+    if (err.code === 'commander.unknownCommand') {
+        return `${err.message}\n\nRun \`gent\` (no args) to see the command list, or \`gent help <command>\` for details.`;
+    }
+    return err.message;
+}
+
+function showQuickstart() {
+    console.log();
+    console.log(chalk.bold.cyan('Gent CLI ') + chalk.gray(`v${packageJson.version}`));
+    console.log(chalk.gray('A Git-like VCS with cloud sync + AI superpowers.\n'));
+    console.log(chalk.bold('First time? Try:'));
+    console.log(`  ${chalk.cyan('gent setup')}              ${chalk.gray('interactive walkthrough (login + AI key + remote)')}`);
+    console.log(`  ${chalk.cyan('gent doctor')}             ${chalk.gray('check everything is wired up')}`);
+    console.log(`  ${chalk.cyan('gent template list')}      ${chalk.gray('scaffold a starter project')}`);
+    console.log();
+    console.log(chalk.bold('Everyday flow:'));
+    console.log(`  ${chalk.cyan('gent init && gent add -A && gent commit -m "init"')}`);
+    console.log(`  ${chalk.cyan('gent push')} / ${chalk.cyan('gent pull')} / ${chalk.cyan('gent merge <branch>')}`);
+    console.log();
+    console.log(chalk.bold('AI features (need an Anthropic key):'));
+    console.log(`  ${chalk.cyan('gent ask "what does this repo do?"')}`);
+    console.log(`  ${chalk.cyan('gent review')}             ${chalk.gray('review staged changes')}`);
+    console.log(`  ${chalk.cyan('gent docs --write')}       ${chalk.gray('generate README.md')}`);
+    console.log(`  ${chalk.cyan('gent changelog')}          ${chalk.gray('grouped release notes')}`);
+    console.log();
+    console.log(chalk.gray('Full command list: ') + chalk.cyan('gent --help'));
+    console.log();
+}
+
 // Error handling
 program.exitOverride();
 
 try {
-    program.parse(process.argv);
-
-    // Show help if no command provided
+    // Show quickstart if no command provided (instead of raw help).
     if (!process.argv.slice(2).length) {
-        program.outputHelp();
+        showQuickstart();
+        process.exit(0);
     }
+
+    program.parse(process.argv);
+
 } catch (err) {
     if (err.code !== 'commander.help' && err.code !== 'commander.helpDisplayed' && err.code !== 'commander.version') {
-        console.error(chalk.red('Error:'), err.message);
+        console.error(chalk.red('Error:'), explainError(err));
         process.exit(1);
     }
 }

package/src/utils/ai-service.js

@@ -0,0 +1,219 @@
+/**
+ * ============================================================================
+ * AI Service - Optional, key-gated Claude integration (hybrid layer)
+ * ============================================================================
+ *
+ * PURPOSE:
+ *   Power Gent's *optional* "smart" features (commit-message suggestions, diff
+ *   explanations, AI-assisted conflict resolution). Every feature has a
+ *   reliable algorithmic path; this layer only activates when the user has set
+ *   an API key, and degrades gracefully (never throws into a command) when it
+ *   is absent or the request fails.
+ *
+ * ENABLEMENT:
+ *   Either set ANTHROPIC_API_KEY in the environment, OR save it once with
+ *   `gent config set ai.api_key <key>` (stored in ~/.gent/cli-config.json).
+ *   Optionally pick a model with GENT_AI_MODEL or `gent config set ai.model`.
+ *   Default model: claude-opus-4-7. For a cheaper / faster option try
+ *   claude-haiku-4-5 or claude-sonnet-4-6.
+ *
+ * IMPLEMENTATION NOTE:
+ *   Calls the Anthropic Messages API (POST /v1/messages) directly over the
+ *   project's existing `axios` dependency, to honour Gent's "no new runtime
+ *   dependencies" constraint. A production app would normally use the official
+ *   `@anthropic-ai/sdk`; raw HTTP is a deliberate trade-off here because the AI
+ *   layer is optional and self-contained.
+ *
+ * ============================================================================
+ */
+
+const axios = require('axios');
+const userConfig = require('./user-config');
+
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const API_VERSION = '2023-06-01';
+const DEFAULT_MODEL = 'claude-opus-4-7';
+
+// Per-process cache so repeated AI calls don't keep hitting disk.
+let _resolvedKey;
+let _resolvedKeySource;
+let _resolvedModel;
+
+async function resolveKey() {
+    if (_resolvedKey !== undefined) {
+        return { value: _resolvedKey, source: _resolvedKeySource };
+    }
+    const r = await userConfig.getResolved('ai.api_key');
+    _resolvedKey = r.value || null;
+    _resolvedKeySource = r.source;
+    return { value: _resolvedKey, source: _resolvedKeySource };
+}
+
+async function resolveModel() {
+    if (_resolvedModel) return _resolvedModel;
+    const r = await userConfig.getResolved('ai.model');
+    _resolvedModel = r.value || DEFAULT_MODEL;
+    return _resolvedModel;
+}
+
+/**
+ * Synchronous getter used in hot paths. Returns whatever was last resolved,
+ * or falls back to env-only (the original behavior) on cold start.
+ */
+function getApiKey() {
+    if (_resolvedKey !== undefined) return _resolvedKey;
+    return process.env.ANTHROPIC_API_KEY || null;
+}
+
+function getModel() {
+    if (_resolvedModel) return _resolvedModel;
+    return process.env.GENT_AI_MODEL || DEFAULT_MODEL;
+}
+
+/**
+ * Async pre-flight resolver — call once from a command before doing AI work
+ * so isEnabled()/getModel() see the user-config values even if env is empty.
+ */
+async function prime() {
+    await resolveKey();
+    await resolveModel();
+}
+
+function isEnabled() {
+    return !!getApiKey();
+}
+
+function disabledHint() {
+    return 'AI features are off — save a key with `gent config set ai.api_key <key>` or set ANTHROPIC_API_KEY in your env.';
+}
+
+/**
+ * Low-level single-shot completion. Returns the assistant's text.
+ * @param {Object} opts
+ * @param {String} opts.prompt - user content
+ * @param {String} [opts.system] - system prompt
+ * @param {Number} [opts.maxTokens]
+ * @returns {Promise<String>}
+ */
+async function complete({ prompt, system, maxTokens = 1024, thinking = false }) {
+    // Make sure env/config-stored values are resolved even if the caller
+    // didn't prime() first.
+    await prime();
+
+    const apiKey = getApiKey();
+    if (!apiKey) throw new Error('AI not enabled');
+
+    const body = {
+        model: getModel(),
+        max_tokens: maxTokens,
+        messages: [{ role: 'user', content: prompt }]
+    };
+    if (system) body.system = system;
+    // Adaptive thinking — opt-in per caller. We leave display at the API
+    // default ("omitted") so reasoning never leaks into CLI output; this just
+    // lets the model think harder on complex tasks (review, conflict resolve)
+    // without changing what the user sees.
+    if (thinking) body.thinking = { type: 'adaptive' };
+
+    try {
+        const res = await axios.post(API_URL, body, {
+            headers: {
+                'x-api-key': apiKey,
+                'anthropic-version': API_VERSION,
+                'content-type': 'application/json'
+            },
+            timeout: 60000
+        });
+
+        const blocks = (res.data && res.data.content) || [];
+        return blocks
+            .filter(b => b.type === 'text')
+            .map(b => b.text)
+            .join('')
+            .trim();
+    } catch (err) {
+        throw enrichAiError(err);
+    }
+}
+
+/**
+ * Wrap raw Anthropic errors with hints that actually help the user.
+ */
+function enrichAiError(err) {
+    const status = err?.response?.status;
+    const apiMsg = err?.response?.data?.error?.message || err?.response?.data?.message;
+    if (status === 401) {
+        return new Error('Anthropic rejected the API key (401). Check `gent config get ai.api_key` and try `gent ai test`.');
+    }
+    if (status === 404 || (apiMsg && /model/i.test(apiMsg))) {
+        return new Error(`Anthropic rejected the model "${getModel()}" — set a valid one with \`gent config set ai.model claude-opus-4-7\`.`);
+    }
+    if (status === 429) {
+        return new Error('Anthropic rate-limited the request (429). Retry in a moment or switch to a lighter model.');
+    }
+    if (apiMsg) return new Error(`AI request failed: ${apiMsg}`);
+    return err;
+}
+
+// ─── High-level helpers ─────────────────────────────────
+
+/**
+ * Suggest a concise commit message from a staged diff / summary.
+ * @param {String} diffSummary
+ * @returns {Promise<String>}
+ */
+async function suggestCommitMessage(diffSummary) {
+    const system =
+        'You write clear, conventional git commit messages. Reply with ONLY the commit ' +
+        'message: a concise imperative subject line (<=72 chars), optionally followed by ' +
+        'a blank line and short body. No quotes, no preamble, no markdown fences.';
+    const prompt = `Write a commit message for these staged changes:\n\n${diffSummary}`;
+    return complete({ system, prompt, maxTokens: 512 });
+}
+
+/**
+ * Explain a commit or diff in plain language.
+ * @param {String} content - diff or commit details
+ * @returns {Promise<String>}
+ */
+async function explainChanges(content) {
+    const system =
+        'You are a senior engineer explaining a code change to a teammate. Summarize what ' +
+        'changed and why it matters in a few short bullet points. Be specific and concise.';
+    const prompt = `Explain these changes:\n\n${content}`;
+    return complete({ system, prompt, maxTokens: 1024 });
+}
+
+/**
+ * Propose a resolution for a single merge-conflict hunk.
+ * @param {Object} hunk - { base?, ours, theirs, fileName? }
+ * @returns {Promise<String>} the suggested merged text (no conflict markers)
+ */
+async function resolveConflictHunk({ base, ours, theirs, fileName }) {
+    const system =
+        'You resolve git merge conflicts. Combine the intent of BOTH sides into a single ' +
+        'correct version. Reply with ONLY the resolved file section — no conflict markers, ' +
+        'no explanation, no markdown fences.';
+    const prompt =
+        `File: ${fileName || 'unknown'}\n\n` +
+        `<<<<<<< BASE (common ancestor)\n${base || '(none)'}\n` +
+        `======= OURS\n${ours}\n` +
+        `======= THEIRS\n${theirs}\n>>>>>>>\n\n` +
+        'Return the merged result for this section.';
+    return complete({ system, prompt, maxTokens: 2048, thinking: true });
+}
+
+module.exports = {
+    isEnabled,
+    getModel,
+    getApiKey,
+    disabledHint,
+    prime,
+    resolveKey,
+    resolveModel,
+    complete,
+    suggestCommitMessage,
+    explainChanges,
+    resolveConflictHunk,
+    DEFAULT_MODEL,
+};

package/src/utils/api-client.js

@@ -5,11 +5,26 @@
 
 const axios = require('axios');
 const { API_BASE_URL } = require('./constants');
+const userConfig = require('./user-config');
 const authStorage = require('./auth-storage');
 
-// Create axios instance with base configuration
+// Resolved once per process so commands see a stable URL. CLI runs are short,
+// so we don't bother with cache invalidation — the next invocation re-reads.
+let _resolvedBaseUrl = null;
+async function resolveBaseUrl() {
+    if (_resolvedBaseUrl) return _resolvedBaseUrl;
+    try {
+        const { value } = await userConfig.getResolved('api.base_url');
+        _resolvedBaseUrl = value || API_BASE_URL;
+    } catch {
+        _resolvedBaseUrl = API_BASE_URL;
+    }
+    return _resolvedBaseUrl;
+}
+
+// Create axios instance with base configuration. baseURL is set per-request
+// by the interceptor below so config/env changes take effect immediately.
 const apiClient = axios.create({
-    baseURL: API_BASE_URL,
     headers: {
         'Content-Type': 'application/json'
     },
@@ -37,9 +52,13 @@ function processQueue(error, token = null) {
     failedRequestsQueue = [];
 }
 
-// Request interceptor - Add JWT token to headers
+// Request interceptor - Resolve base URL + add JWT token to headers
 apiClient.interceptors.request.use(
     async (config) => {
+        if (!config.baseURL) {
+            config.baseURL = await resolveBaseUrl();
+        }
+
         const token = await authStorage.getAccessToken();
 
         if (token) {
@@ -89,9 +108,11 @@ apiClient.interceptors.response.use(
                     throw new Error('Session expired. Please login again.');
                 }
 
-                // Call refresh endpoint
+                // Call refresh endpoint (raw axios — bypasses our interceptor
+                // intentionally so a 401 here doesn't loop back into refresh).
+                const baseUrl = await resolveBaseUrl();
                 const response = await axios.post(
-                    `${API_BASE_URL}/api/auth/token/refresh/`,
+                    `${baseUrl}/api/auth/token/refresh/`,
                     { refresh: refreshToken }
                 );
 
@@ -188,5 +209,6 @@ module.exports = {
     put,
     delete: del,
     patch,
-    apiClient // Export raw client if needed
+    apiClient, // Export raw client if needed
+    resolveBaseUrl,
 };

package/src/utils/constants.js

@@ -12,7 +12,9 @@ module.exports = {
     HEAD_FILE: 'HEAD',
     AUTH_FILE: 'auth.json',
 
-    // API Configuration
+    // API Configuration — default used when no env/config override.
+    // Use getResolvedApiBaseUrl() in code that runs after process boot
+    // to respect GENT_API_URL env or user config (~/.gent/cli-config.json).
     API_BASE_URL: 'https://gent-api.onrender.com',
     API_ENDPOINTS: {
         // Auth