@dccxx/auggiegw 1.0.5 → 1.0.7

package/README.md

@@ -1,104 +1,483 @@
 # @dccxx/auggiegw
 
-A Node.js TypeScript package with CLI support.
+A CLI tool for managing Augment Gateway authentication, proxy configuration, and custom prompts. This tool simplifies the workflow of authenticating with Augment Gateway, fetching proxy configurations, and managing custom prompts for the Augment AI assistant.
+
+## Features
+
+- 🔐 **Authentication Management**: Login/logout with secure credential storage
+- 🌐 **Proxy Configuration**: Automatic proxy setup and authentication
+- 📝 **Custom Prompts**: Fetch and save custom prompts to `~/.augment/commands/`
+- 🔄 **Auggie Integration**: Seamlessly forward commands to the Auggie CLI
+- ⚡ **Command Execution**: Execute any command with automatic session setup
 
 ## Installation
 
-Install dependencies:
+```bash
+npm install -g @dccxx/auggiegw
+```
+
+or with Bun:
 
 ```bash
-bun install
+bun install -g @dccxx/auggiegw
 ```
 
-## Development
+## Quick Start
 
-Build the project:
+1. **Login to Augment Gateway**:
+   ```bash
+   auggiegw login
+   ```
+   You'll be prompted for your username and password.
 
+2. **Fetch Configuration**:
+   ```bash
+   auggiegw fetch
+   ```
+   This fetches proxy configuration, authenticates, and downloads custom prompts.
+
+## Global Options
+
+The following options can be used with any command that triggers session management (`fetch`, `auggie`, `exec`):
+
+- **`--preserve-session`**: Preserve Auggie session and chat history when switching accounts
+- **`--delete-session`**: Explicitly delete Auggie session and chat history (default behavior)
+
+**Examples**:
 ```bash
-bun run build
+# Preserve chat history when fetching
+auggiegw --preserve-session fetch
+
+# Preserve chat history when running auggie
+auggiegw --preserve-session auggie --help
+
+# Explicitly delete session (same as default)
+auggiegw --delete-session fetch
 ```
 
-Run linter:
+**Precedence Order** (highest to lowest):
+1. Command-line flags (`--preserve-session` or `--delete-session`)
+2. Environment variable (`AUGGIEGW_DELETE_SESSION`)
+3. Default behavior (delete session)
+
+---
+
+## Commands
+
+### `auggiegw login [username] [password]`
+
+Login and store credentials securely.
 
+**Interactive Mode** (Recommended):
 ```bash
-bun run lint
+auggiegw login
 ```
+You'll be prompted to enter your username and password. The password input is hidden for security.
+
+**Direct Mode**:
+```bash
+auggiegw login myusername mypassword
+```
+
+**What it does**:
+- Authenticates with the Augment Gateway API
+- Stores credentials in `~/.auggiegw/auth.json`
+- Token is used for subsequent commands
+
+---
 
-Clean build artifacts:
+### `auggiegw logout`
+
+Logout and remove stored credentials.
 
 ```bash
-bun run clean
+auggiegw logout
 ```
 
-## Usage
+**What it does**:
+- Deletes the authentication file (`~/.auggiegw/auth.json`)
+- Removes stored credentials from your system
 
-### Authentication
+---
 
-There are two ways to authenticate with auggiegw:
+### `auggiegw fetch`
 
-#### 1. Using Environment Variable (Recommended for CI/CD)
+Fetch proxy configuration, authenticate, and download custom prompts.
 
-Set the `AUGGIEGW_AUTH_TOKEN` environment variable with your authentication token:
+**Basic Usage**:
+```bash
+auggiegw fetch
+```
 
+**With Session Control**:
 ```bash
-export AUGGIEGW_AUTH_TOKEN=your_token_here
+# Preserve chat history
+auggiegw --preserve-session fetch
+
+# Explicitly delete session (default)
+auggiegw --delete-session fetch
 ```
 
-When this environment variable is set, the CLI will use it directly without requiring login or auth.json file.
+**What it does**:
+1. Retrieves proxy configuration from Augment Gateway
+2. Authenticates the proxy
+3. Saves Augment session to `~/.augment/session.json`
+4. Deletes Auggie session (unless `--preserve-session` is used)
+5. Fetches all custom prompts from the server
+6. Saves prompts as markdown files in `~/.augment/commands/`
+
+**Output Example**:
+```
+✔ Successfully saved 15 prompts
+```
 
-#### 2. Using Login Command
+---
 
-Login with your credentials:
+### `auggiegw auggie [args...]`
 
+Forward commands to the Auggie CLI with automatic configuration.
+
+**Basic Usage**:
 ```bash
-auggiegw login [username] [password]
+auggiegw auggie [auggie-arguments]
 ```
 
-This will save your credentials to `~/.auggiegw/auth.json` for future use.
+**Examples**:
+```bash
+# Run Auggie with help
+auggiegw auggie --help
+
+# Run Auggie and preserve chat history
+auggiegw --preserve-session auggie
+
+# Run Auggie with a specific prompt
+auggiegw --preserve-session auggie --print "Hello, world!"
+```
 
-### CLI Commands
+**What it does**:
+1. Runs `auggiegw fetch` to ensure configuration is up-to-date
+2. Deletes Auggie session (unless `--preserve-session` is used)
+3. Forwards all arguments to the `auggie` command
+4. Inherits stdio for interactive sessions
 
-#### Login
+---
+
+### `auggiegw exec <command> [args...]`
+
+Execute any custom command with automatic session setup.
+
+**Basic Usage**:
 ```bash
-auggiegw login [username] [password]
+auggiegw exec <command> [arguments]
 ```
 
-#### Logout
+**Examples**:
 ```bash
-auggiegw logout
+# Execute auggie with help
+auggiegw exec auggie --help
+
+# Execute with preserved session
+auggiegw --preserve-session exec auggie --help
+
+# Execute custom command
+auggiegw --preserve-session exec node script.js
+```
+
+**What it does**:
+1. Runs `auggiegw fetch` to ensure configuration is up-to-date
+2. Deletes Auggie session (unless `--preserve-session` is used)
+3. Executes the specified command with provided arguments
+4. Inherits stdio for interactive sessions
+
+---
+
+## Authentication Methods
+
+### Method 1: Login Command (Recommended for Local Development)
+
+```bash
+auggiegw login
+```
+
+Credentials are stored in `~/.auggiegw/auth.json` and automatically used for subsequent commands.
+
+### Method 2: Environment Variable (Recommended for CI/CD)
+
+Set the `AUGGIEGW_AUTH_TOKEN` environment variable:
+
+```bash
+export AUGGIEGW_AUTH_TOKEN=your_token_here
+```
+
+When this environment variable is set, the CLI uses it directly without requiring the login command or auth.json file.
+
+**Example in CI/CD**:
+```yaml
+# GitHub Actions example
+env:
+  AUGGIEGW_AUTH_TOKEN: ${{ secrets.AUGGIEGW_AUTH_TOKEN }}
 ```
 
-#### Fetch proxy configuration and prompts
+---
+
+## Configuration
+
+### Session Management
+
+The CLI provides multiple ways to control session deletion behavior when switching accounts:
+
+#### 1. Command-Line Flags (Highest Priority)
+
+Use global options with any command:
+
 ```bash
+# Preserve session for a single command
+auggiegw --preserve-session fetch
+
+# Explicitly delete session (default behavior)
+auggiegw --delete-session fetch
+```
+
+#### 2. Environment Variable
+
+Set `AUGGIEGW_DELETE_SESSION` to control default behavior:
+
+```bash
+# Preserve sessions by default
+export AUGGIEGW_DELETE_SESSION=false
 auggiegw fetch
+
+# Delete sessions by default (same as built-in default)
+export AUGGIEGW_DELETE_SESSION=true
+auggiegw fetch
+```
+
+#### 3. Default Behavior (Lowest Priority)
+
+By default, the CLI deletes the Auggie session (including chat history) when fetching configuration to ensure a clean state for each account.
+
+**Precedence Order**:
+1. **Command-line flags** (`--preserve-session` or `--delete-session`) - Always takes precedence
+2. **Environment variable** (`AUGGIEGW_DELETE_SESSION`) - Used if no CLI flag is provided
+3. **Default behavior** (delete session) - Used if neither flag nor environment variable is set
+
+**Examples**:
+
+```bash
+# CLI flag overrides environment variable
+export AUGGIEGW_DELETE_SESSION=false
+auggiegw --delete-session fetch  # Session WILL be deleted
+
+# Environment variable is used when no flag is provided
+export AUGGIEGW_DELETE_SESSION=false
+auggiegw fetch  # Session will NOT be deleted
+
+# Default behavior when nothing is set
+unset AUGGIEGW_DELETE_SESSION
+auggiegw fetch  # Session WILL be deleted (default)
+```
+
+### Environment Variables
+
+- **`AUGGIEGW_AUTH_TOKEN`**: Authentication token for API access (alternative to login command)
+- **`AUGGIEGW_DELETE_SESSION`**: Control Auggie session deletion behavior
+  - Set to `false` to preserve chat history when switching accounts
+  - Set to `true` or leave unset for default behavior (delete session)
+  - Can be overridden by command-line flags
+
+### File Locations
+
+- **Auth Data**: `~/.auggiegw/auth.json`
+- **Augment Session**: `~/.augment/session.json`
+- **Custom Prompts**: `~/.augment/commands/*.md`
+
+---
+
+## Custom Prompts
+
+Custom prompts are fetched from the Augment Gateway and saved as markdown files in `~/.augment/commands/`. Each prompt file follows this format:
+
+```markdown
+---
+description: Prompt Name
+---
+
+Prompt content goes here...
 ```
 
-#### Forward command to auggie CLI
+The filename corresponds to the command name (e.g., `my-command.md`).
+
+---
+
+## Usage Examples
+
+### Switching Accounts with Preserved Chat History
+
 ```bash
-auggiegw auggie [args...]
+# Method 1: Using command-line flag
+auggiegw login user1
+auggiegw --preserve-session fetch
+auggiegw --preserve-session auggie
+
+# Switch to another account
+auggiegw login user2
+auggiegw --preserve-session fetch
+auggiegw --preserve-session auggie
 ```
 
-#### Execute custom command
+### Switching Accounts with Clean Sessions (Default)
+
 ```bash
-auggiegw exec <command> [args...]
+# Default behavior - session is deleted
+auggiegw login user1
+auggiegw fetch
+auggiegw auggie
+
+# Switch to another account - previous session is cleared
+auggiegw login user2
+auggiegw fetch
+auggiegw auggie
 ```
 
-### As a library
+### Using Environment Variable for Multiple Commands
 
-Import and use in your Node.js project:
+```bash
+# Set environment variable once
+export AUGGIEGW_DELETE_SESSION=false
+
+# All subsequent commands preserve session
+auggiegw login user1
+auggiegw fetch
+auggiegw auggie
 
-```typescript
-import '@dccxx/auggiegw';
+# Switch accounts without losing history
+auggiegw login user2
+auggiegw fetch
+auggiegw auggie
 ```
 
-## Project Structure
+### Override Environment Variable with CLI Flag
 
-- `src/` - TypeScript source files
-- `dist/` - Compiled JavaScript output (generated by build)
-- `tsconfig.json` - TypeScript configuration
-- `biome.json` - Biome linter configuration
+```bash
+# Set default to preserve
+export AUGGIEGW_DELETE_SESSION=false
+
+# This preserves session (follows env var)
+auggiegw fetch
+
+# This deletes session (CLI flag overrides env var)
+auggiegw --delete-session fetch
+```
+
+### CI/CD Pipeline Example
+
+```yaml
+# GitHub Actions workflow
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup authentication
+        env:
+          AUGGIEGW_AUTH_TOKEN: ${{ secrets.AUGGIEGW_AUTH_TOKEN }}
+          AUGGIEGW_DELETE_SESSION: true
+        run: |
+          auggiegw fetch
+          auggiegw exec npm run deploy
+```
+
+---
 
 ## Requirements
 
-- Node.js >= 18.0.0
-- Bun (for package management and running scripts)
+- **Node.js**: >= 18.0.0
+- **Bun**: For package management and running scripts (development)
+- **Auggie CLI**: Required for `auggiegw auggie` command
+
+---
+
+## Troubleshooting
+
+### "Not logged in" Error
+
+```
+Error: Not logged in. Please run "auggiegw login" first.
+```
+
+**Solution**: Run `auggiegw login` to authenticate.
+
+### "Failed to get proxy" Error
+
+**Possible causes**:
+- Invalid credentials
+- Network connectivity issues
+- API endpoint unavailable
+
+**Solution**: 
+1. Verify your credentials with `auggiegw logout` then `auggiegw login`
+2. Check your network connection
+3. Verify the API URL is correct
+
+### "No proxy data available" Error
+
+**Solution**: Contact your administrator to ensure your account has proxy access configured.
+
+### Chat History Lost When Switching Accounts
+
+By default, the CLI deletes the Auggie session (including chat history) when fetching configuration. This ensures a clean state for each account.
+
+**Solution 1: Use Command-Line Flag (Recommended)**
+
+Preserve session for specific commands:
+
+```bash
+# Login to new account
+auggiegw login newuser
+
+# Fetch with preserved session
+auggiegw --preserve-session fetch
+
+# Or use with auggie command
+auggiegw --preserve-session auggie
+```
+
+**Solution 2: Use Environment Variable**
+
+Set a persistent default behavior:
+
+```bash
+# Set the environment variable to disable session deletion
+export AUGGIEGW_DELETE_SESSION=false
+
+# Then run your commands as usual
+auggiegw login newuser
+auggiegw fetch
+```
+
+**Solution 3: Mixed Approach**
+
+Combine both methods for flexibility:
+
+```bash
+# Set default to preserve
+export AUGGIEGW_DELETE_SESSION=false
+
+# Most commands will preserve session
+auggiegw fetch
+
+# But you can override for specific commands
+auggiegw --delete-session fetch  # This will delete the session
+```
+
+**Note**: Disabling session deletion may cause conflicts if different accounts have incompatible session data. Use this option only if you need to preserve chat history across account switches.
+
+---
+
+## License
+
+See LICENSE file for details.
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.
+

package/dist/cli.js

@@ -19,6 +19,29 @@ function loadConfig() {
     const apiUrl = process.env.AUGMENT_GATEWAY_URL || 'https://augmentgateway.1app.space';
     return { apiUrl };
 }
+function getSessionOptions(opts) {
+    const sessionOptions = {};
+    // CLI flags take precedence
+    if (opts.preserveSession) {
+        sessionOptions.deleteSession = false;
+    }
+    else if (opts.deleteSession) {
+        sessionOptions.deleteSession = true;
+    }
+    return sessionOptions;
+}
+function shouldDeleteSession(options) {
+    // Priority: CLI flag > Environment variable > Default (true)
+    if (options?.deleteSession !== undefined) {
+        return options.deleteSession;
+    }
+    // Check environment variable
+    if (process.env.AUGGIEGW_DELETE_SESSION !== undefined) {
+        return process.env.AUGGIEGW_DELETE_SESSION !== 'false';
+    }
+    // Default behavior: delete session
+    return true;
+}
 async function ensureAuthDirectory() {
     try {
         await fs.mkdir(AUTH_DIR, { recursive: true });
@@ -250,7 +273,7 @@ async function handleLogout() {
         process.exit(1);
     }
 }
-async function handleFetch() {
+async function handleFetch(options) {
     const spinner = ora('Initializing...').start();
     try {
         const config = loadConfig();
@@ -283,11 +306,14 @@ async function handleFetch() {
                 scopes: ['read', 'write'],
             };
             await saveAugmentSession(augmentSession);
-            try {
-                await execAsync('auggie session delete');
-            }
-            catch {
-                // Silently ignore auggie session delete errors
+            // Check if session deletion is enabled
+            if (shouldDeleteSession(options)) {
+                try {
+                    await execAsync('auggie session delete');
+                }
+                catch {
+                    // Silently ignore auggie session delete errors
+                }
             }
             spinner.text = 'Fetching prompts...';
             const allPrompts = await getAllPrompts(token, config.apiUrl, spinner);
@@ -308,8 +334,8 @@ async function handleFetch() {
         process.exit(1);
     }
 }
-async function handleAuggie(args) {
-    await handleFetch();
+async function handleAuggie(args, options) {
+    await handleFetch(options);
     const auggieProcess = spawn('auggie', args, {
         stdio: 'inherit',
         shell: true,
@@ -322,13 +348,13 @@ async function handleAuggie(args) {
         process.exit(code ?? 0);
     });
 }
-async function handleExec(command, args) {
+async function handleExec(command, args, options) {
     if (!command) {
         console.error('Error: Command is required');
         console.error('Usage: auggiegw exec <command> [args...]');
         process.exit(1);
     }
-    await handleFetch();
+    await handleFetch(options);
     const childProcess = spawn(command, args, {
         stdio: 'inherit',
         shell: true,
@@ -342,7 +368,12 @@ async function handleExec(command, args) {
     });
 }
 const program = new Command();
-program.name('auggiegw').description('CLI tool for auggiegw authentication').version('1.0.0');
+program
+    .name('auggiegw')
+    .description('CLI tool for auggiegw authentication')
+    .version('1.0.0')
+    .option('--preserve-session', 'Preserve Auggie session (do not delete chat history)')
+    .option('--delete-session', 'Delete Auggie session (clear chat history)');
 program
     .command('login [username] [password]')
     .description('Login and store credentials')
@@ -351,20 +382,28 @@ program.command('logout').description('Logout and remove stored credentials').ac
 program
     .command('fetch')
     .description('Fetch proxy configuration and authenticate')
-    .action(handleFetch);
+    .action(() => {
+    const opts = program.opts();
+    const sessionOptions = getSessionOptions(opts);
+    handleFetch(sessionOptions);
+});
 program
     .command('auggie [args...]')
     .description('Forward command to auggie CLI')
     .allowUnknownOption()
     .action((args) => {
-    handleAuggie(args || []);
+    const opts = program.opts();
+    const sessionOptions = getSessionOptions(opts);
+    handleAuggie(args || [], sessionOptions);
 });
 program
     .command('exec <command> [args...]')
     .description('Execute any custom command')
     .allowUnknownOption()
     .action((command, args) => {
-    handleExec(command, args);
+    const opts = program.opts();
+    const sessionOptions = getSessionOptions(opts);
+    handleExec(command, args, sessionOptions);
 });
 program.parse();
 //# sourceMappingURL=cli.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dccxx/auggiegw",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A Node.js TypeScript package",
   "main": "./dist/cli.js",
   "types": "./dist/cli.d.ts",