gent-cli 7.0.0 → 9.0.0

package/src/index.js

@@ -7,19 +7,25 @@
  * ============================================================================
  *
  * COMMANDS:
+ *   Setup:       setup, config, doctor
  *   Repository:  init, clone
  *   Staging:     add, rm, reset, status, diff
  *   History:     commit, log, show, tag, explain
  *   Branching:   branch, checkout, merge, resolve, stash
  *   Safety:      undo, redo
- *   Insight:     summary
- *   Remote:      remote, push, pull
- *   Auth:        register, login, logout, whoami
+ *   Insight:     summary, ask, review, docs, changelog
+ *   Remote:      remote, repos, members, push, pull, search, web, share
+ *   Auth:        register, login, logout, whoami, password
+ *   AI:          ai (status|test|models)
+ *   Templates:   template (list|use)
  *
  * @author Abdalrahman Kanawati
  * @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');
@@ -44,6 +50,7 @@ const remoteCommand = require('./commands/remote');
 const pushCommand = require('./commands/push');
 const pullCommand = require('./commands/pull');
 const reposCommand = require('./commands/repos');
+const membersCommand = require('./commands/members');
 const undoCommand = require('./commands/undo');
 const resolveCommand = require('./commands/resolve');
 const summaryCommand = require('./commands/summary');
@@ -54,6 +61,21 @@ const registerCommand = require('./commands/register');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
 const whoamiCommand = require('./commands/whoami');
+const passwordCommand = require('./commands/password');
+
+// 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
@@ -84,10 +106,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...>')
@@ -215,6 +243,12 @@ program
     .option('--default-branch <name>', 'Default branch name (with --create)')
     .action(reposCommand);
 
+program
+    .command('members [action] [email]')
+    .description('Manage repo collaborators (list | add <email> | remove <email>)')
+    .option('--role <role>', 'Role when adding a member: write or read', 'write')
+    .action(membersCommand);
+
 program
     .command('push [remote] [branch]')
     .description('Push local commits to remote')
@@ -226,6 +260,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
@@ -255,6 +366,12 @@ program
     .description('Display current user information')
     .action(whoamiCommand);
 
+program
+    .command('password [action]')
+    .description('Change or reset your password (change | reset [email] | reset-confirm)')
+    .option('-e, --email <email>', 'Account email (for reset)')
+    .action(passwordCommand);
+
 // Help command
 program
     .command('help [command]')
@@ -267,19 +384,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/services/auth-service.js

@@ -138,10 +138,9 @@ async function refreshToken() {
             refresh: refreshToken
         });
 
-        const { access } = response;
-
-        // Update only access token
-        await authStorage.updateAccessToken(access);
+        // Backend rotates refresh tokens, so persist the new one too.
+        const { access, refresh } = response;
+        await authStorage.updateTokens(access, refresh);
 
         return access;
     } catch (error) {

package/src/utils/ai-service.js

@@ -11,9 +11,11 @@
  *   is absent or the request fails.
  *
  * ENABLEMENT:
- *   Set ANTHROPIC_API_KEY in the environment to enable. Optionally set
- *   GENT_AI_MODEL to pick a model (default: claude-opus-4-8). For a cheaper /
- *   faster option set GENT_AI_MODEL=claude-haiku-4-5.
+ *   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
@@ -26,39 +28,63 @@
  */
 
 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-8';
+const DEFAULT_MODEL = 'claude-opus-4-7';
 
-/**
- * Resolve the API key (env only — keeps secrets out of the repo).
- * @returns {String|null}
- */
-function getApiKey() {
-    return process.env.ANTHROPIC_API_KEY || null;
+// 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 };
 }
 
-/**
- * @returns {Boolean} whether AI features are enabled.
- */
-function isEnabled() {
-    return !!getApiKey();
+async function resolveModel() {
+    if (_resolvedModel) return _resolvedModel;
+    const r = await userConfig.getResolved('ai.model');
+    _resolvedModel = r.value || DEFAULT_MODEL;
+    return _resolvedModel;
 }
 
 /**
- * @returns {String} the model id to use.
+ * 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;
 }
 
 /**
- * One-line hint shown by commands when AI is requested but no key is set.
- * @returns {String}
+ * 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 — set ANTHROPIC_API_KEY to enable (optional: GENT_AI_MODEL).';
+    return 'AI features are off — save a key with `gent config set ai.api_key <key>` or set ANTHROPIC_API_KEY in your env.';
 }
 
 /**
@@ -69,7 +95,11 @@ function disabledHint() {
  * @param {Number} [opts.maxTokens]
  * @returns {Promise<String>}
  */
-async function complete({ prompt, system, maxTokens = 1024 }) {
+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');
 
@@ -79,22 +109,50 @@ async function complete({ prompt, system, maxTokens = 1024 }) {
         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);
+    }
+}
 
-    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();
+/**
+ * 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 ─────────────────────────────────
@@ -142,15 +200,20 @@ async function resolveConflictHunk({ base, ours, theirs, fileName }) {
         `======= OURS\n${ours}\n` +
         `======= THEIRS\n${theirs}\n>>>>>>>\n\n` +
         'Return the merged result for this section.';
-    return complete({ system, prompt, maxTokens: 2048 });
+    return complete({ system, prompt, maxTokens: 2048, thinking: true });
 }
 
 module.exports = {
     isEnabled,
     getModel,
+    getApiKey,
     disabledHint,
+    prime,
+    resolveKey,
+    resolveModel,
     complete,
     suggestCommitMessage,
     explainChanges,
-    resolveConflictHunk
+    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,16 +108,19 @@ 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 }
                 );
 
-                const { access } = response.data;
-
-                // Update stored access token
-                await authStorage.updateAccessToken(access);
+                // Backend rotates refresh tokens (ROTATE_REFRESH_TOKENS +
+                // BLACKLIST_AFTER_ROTATION); persist the new refresh or the
+                // next silent refresh sends a blacklisted token and 401s.
+                const { access, refresh } = response.data;
+                await authStorage.updateTokens(access, refresh);
 
                 // Update authorization header
                 originalRequest.headers.Authorization = `Bearer ${access}`;
@@ -188,5 +210,6 @@ module.exports = {
     put,
     delete: del,
     patch,
-    apiClient // Export raw client if needed
+    apiClient, // Export raw client if needed
+    resolveBaseUrl,
 };

package/src/utils/auth-storage.js

@@ -136,10 +136,13 @@ async function clearAuth() {
 }
 
 /**
- * Update only the access token (used after refresh)
+ * Update stored tokens after a refresh. The backend rotates refresh tokens
+ * (ROTATE_REFRESH_TOKENS + BLACKLIST_AFTER_ROTATION), so the new refresh token
+ * MUST be persisted or the next refresh sends a blacklisted token and 401s.
  * @param {string} newAccessToken - New access token
+ * @param {string} [newRefreshToken] - New (rotated) refresh token, if returned
  */
-async function updateAccessToken(newAccessToken) {
+async function updateTokens(newAccessToken, newRefreshToken) {
     const authData = await readAuthData();
 
     if (!authData) {
@@ -147,6 +150,9 @@ async function updateAccessToken(newAccessToken) {
     }
 
     authData.accessToken = newAccessToken;
+    if (newRefreshToken) {
+        authData.refreshToken = newRefreshToken;
+    }
     authData.timestamp = new Date().toISOString();
 
     const authFilePath = getAuthFilePath();
@@ -158,6 +164,11 @@ async function updateAccessToken(newAccessToken) {
     await fs.writeFile(authFilePath, JSON.stringify({ data: encryptedData }), 'utf8');
 }
 
+// Back-compat alias: same as updateTokens with no rotated refresh.
+async function updateAccessToken(newAccessToken) {
+    return updateTokens(newAccessToken);
+}
+
 module.exports = {
     saveTokens,
     getAccessToken,
@@ -165,5 +176,6 @@ module.exports = {
     getUser,
     isAuthenticated,
     clearAuth,
-    updateAccessToken
+    updateAccessToken,
+    updateTokens
 };

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
@@ -21,6 +23,9 @@ module.exports = {
         LOGOUT: '/api/auth/logout/',
         REFRESH: '/api/auth/token/refresh/',
         PROFILE: '/api/auth/profile/',
+        PASSWORD_CHANGE: '/api/auth/password/change/',
+        PASSWORD_RESET: '/api/auth/password/reset/',
+        PASSWORD_RESET_CONFIRM: '/api/auth/password/reset/confirm/',
 
         // Repository management
         REPOS: '/api/repos/',
@@ -28,9 +33,13 @@ module.exports = {
         // Template: /api/repos/{owner_id}/{repo_name}/
         REPO_DETAIL: '/api/repos/{owner_id}/{repo_name}/',
         REPO_DELETE: '/api/repos/{owner_id}/{repo_name}/delete/',
+        REPO_MEMBERS: '/api/repos/{owner_id}/{repo_name}/members/',
+        REPO_MEMBER_DETAIL: '/api/repos/{owner_id}/{repo_name}/members/{user_id}/',
 
-        // Push
+        // Push / Pull / Clone
         REPO_PUSH: '/api/repos/{owner_id}/{repo_name}/push/',
+        REPO_PULL: '/api/repos/{owner_id}/{repo_name}/pull/',
+        REPO_CLONE: '/api/repos/{owner_id}/{repo_name}/clone/',
 
         // Branches
         REPO_BRANCHES: '/api/repos/{owner_id}/{repo_name}/branches/',