npm - gent-cli - Versions diffs - 7.0.0 → 8.0.0 - Mend

gent-cli 7.0.0 → 8.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/package.json +2 -2
package/src/commands/ai.js +82 -0
package/src/commands/ask.js +121 -0
package/src/commands/changelog.js +121 -0
package/src/commands/clone.js +6 -3
package/src/commands/config.js +147 -0
package/src/commands/docs.js +141 -0
package/src/commands/doctor.js +169 -0
package/src/commands/pull.js +4 -3
package/src/commands/review.js +157 -0
package/src/commands/search.js +77 -0
package/src/commands/setup.js +201 -0
package/src/commands/share.js +63 -0
package/src/commands/template.js +135 -0
package/src/commands/web.js +72 -0
package/src/index.js +151 -10
package/src/utils/ai-service.js +100 -37
package/src/utils/api-client.js +28 -6
package/src/utils/constants.js +3 -1
package/src/utils/env-loader.js +61 -0
package/src/utils/user-config.js +225 -0

package/src/commands/template.js ADDED Viewed

@@ -0,0 +1,135 @@
+/**
+ * Template Command - Quick-start from a baked-in starter.
+ *
+ *   gent template list                       → show available templates
+ *   gent template use <name> [directory]     → scaffold a starter
+ *
+ * Templates are tiny inline definitions — no network needed. Keep them small
+ * so the CLI bundle stays light.
+ */
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const { pathExists, ensureDir } = require('../utils/fileSystem');
+const initCommand = require('./init');
+const TEMPLATES = {
+    node: {
+        description: 'Minimal Node.js project (package.json + index.js)',
+        files: {
+            'package.json': JSON.stringify({
+                name: '__NAME__',
+                version: '0.1.0',
+                main: 'index.js',
+                scripts: { start: 'node index.js' },
+            }, null, 2) + '\n',
+            'index.js': "console.log('hello from __NAME__');\n",
+            '.gentignore': 'node_modules/\n.env\n',
+            'README.md': '# __NAME__\n\nA Node.js project scaffolded with `gent template use node`.\n',
+        },
+    },
+    python: {
+        description: 'Minimal Python project (main.py + requirements.txt)',
+        files: {
+            'main.py': "def main():\n    print('hello from __NAME__')\n\nif __name__ == '__main__':\n    main()\n",
+            'requirements.txt': '',
+            '.gentignore': '__pycache__/\n.venv/\n*.pyc\n.env\n',
+            'README.md': '# __NAME__\n\nA Python project scaffolded with `gent template use python`.\n',
+        },
+    },
+    react: {
+        description: 'Vite + React skeleton (vite-style index.html + src/main.jsx)',
+        files: {
+            'package.json': JSON.stringify({
+                name: '__NAME__',
+                version: '0.1.0',
+                type: 'module',
+                scripts: { dev: 'vite', build: 'vite build', preview: 'vite preview' },
+                dependencies: { react: '^18.3.1', 'react-dom': '^18.3.1' },
+                devDependencies: { vite: '^5.4.0', '@vitejs/plugin-react': '^4.3.1' },
+            }, null, 2) + '\n',
+            'index.html': '<!doctype html>\n<html><head><title>__NAME__</title></head>\n<body><div id="root"></div><script type="module" src="/src/main.jsx"></script></body></html>\n',
+            'src/main.jsx': "import React from 'react';\nimport { createRoot } from 'react-dom/client';\ncreateRoot(document.getElementById('root')).render(<h1>__NAME__</h1>);\n",
+            '.gentignore': 'node_modules/\ndist/\n.env\n',
+            'README.md': '# __NAME__\n\nRun `npm install && npm run dev` to start.\n',
+        },
+    },
+    'django-api': {
+        description: 'Minimal Django project shell (manage.py + settings stub)',
+        files: {
+            'manage.py': "#!/usr/bin/env python\nimport os, sys\nif __name__ == '__main__':\n    os.environ.setdefault('DJANGO_SETTINGS_MODULE', '__NAME__.settings')\n    from django.core.management import execute_from_command_line\n    execute_from_command_line(sys.argv)\n",
+            'requirements.txt': 'Django>=5.0\n',
+            '.gentignore': '__pycache__/\n*.pyc\n.venv/\ndb.sqlite3\n.env\n',
+            'README.md': '# __NAME__\n\nRun `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`.\n',
+        },
+    },
+};
+async function template(subcommand, args = [], options = {}) {
+    const sub = (subcommand || 'list').toLowerCase();
+    switch (sub) {
+        case 'list': return list();
+        case 'use': return use(args[0], args[1], options);
+        default:
+            console.error(chalk.red(`Unknown subcommand '${sub}'`));
+            console.log(chalk.gray('Usage: gent template <list|use>'));
+            process.exit(1);
+    }
+}
+function list() {
+    console.log(chalk.bold.cyan('\nAvailable templates\n'));
+    for (const [name, t] of Object.entries(TEMPLATES)) {
+        console.log(`  ${chalk.cyan(name.padEnd(14))} ${chalk.gray(t.description)}`);
+    }
+    console.log(chalk.gray('\n  Usage: gent template use <name> [directory]\n'));
+}
+async function use(name, directory) {
+    if (!name) {
+        console.error(chalk.red('Usage: gent template use <name> [directory]'));
+        process.exit(1);
+    }
+    const tpl = TEMPLATES[name];
+    if (!tpl) {
+        console.error(chalk.red(`Unknown template '${name}'`));
+        console.log(chalk.gray(`Available: ${Object.keys(TEMPLATES).join(', ')}`));
+        process.exit(1);
+    }
+    const targetDir = directory || name;
+    const targetPath = path.resolve(process.cwd(), targetDir);
+    const projectName = path.basename(targetPath).replace(/[^A-Za-z0-9_-]/g, '-');
+    if (await pathExists(targetPath)) {
+        const entries = await fs.readdir(targetPath);
+        if (entries.length > 0) {
+            console.error(chalk.red(`Directory '${targetDir}' is not empty.`));
+            process.exit(1);
+        }
+    } else {
+        await ensureDir(targetPath);
+    }
+    for (const [rel, content] of Object.entries(tpl.files)) {
+        const filePath = path.join(targetPath, rel);
+        await ensureDir(path.dirname(filePath));
+        const body = content.replace(/__NAME__/g, projectName);
+        await fs.writeFile(filePath, body, 'utf-8');
+    }
+    console.log(chalk.green(`✓ Scaffolded '${name}' into ${targetDir}/`));
+    // Auto-init a gent repo so the next steps work
+    const originalCwd = process.cwd();
+    try {
+        process.chdir(targetPath);
+        await initCommand({});
+    } finally {
+        process.chdir(originalCwd);
+    }
+    console.log(chalk.gray('  Next: cd ' + targetDir + ' && gent add -A && gent commit -m "init"'));
+}
+module.exports = template;

package/src/commands/web.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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
+ *   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 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');
@@ -55,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')
@@ -84,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...>')
@@ -226,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
@@ -267,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 CHANGED Viewed

@@ -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,
 };