@4ge/cli 0.1.0

package/dist/commands/auth/login.js

@@ -0,0 +1,197 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { generateState } from '../../core/auth/state.js';
+import { getSupabaseConfig, subscribeForTokens } from '../../core/auth/realtime.js';
+import { authenticateWithEmail } from '../../core/auth/email-auth.js';
+import { saveCredential } from '../../core/auth/credentials.js';
+import { createApiClient } from '../../core/auth/api-client.js';
+import { getApiBaseUrl } from '../../core/auth/config.js';
+import { cliAuthStatus } from '../../generated/api/sdk.gen.js';
+export default class AuthLogin extends BaseCommand {
+    static description = 'Authenticate the CLI with your 4ge account';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        token: Flags.string({
+            char: 't',
+            description: 'Manually provide an API key or access token',
+        }),
+        email: Flags.boolean({
+            description: 'Force email/password authentication flow',
+            default: false,
+        }),
+        local: Flags.boolean({
+            char: 'l',
+            description: 'Save credentials to local .4ge/credentials.json instead of global',
+            default: false,
+        }),
+        profile: Flags.string({
+            char: 'p',
+            description: 'Name of the profile to save credentials to',
+            default: 'default',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AuthLogin);
+        await this.renderHeader('ready');
+        // 1. Manual Token Flow
+        if (flags.token) {
+            await this.withSpinner('Validating and saving token...', async () => {
+                await this.validateAndSave({
+                    apiKey: flags.token,
+                    local: flags.local,
+                    profile: flags.profile,
+                });
+            });
+            if (this.isJsonMode) {
+                this.outputJson({ message: 'Successfully authenticated with manual token' });
+            }
+            else {
+                this.log('Successfully authenticated with manual token.');
+            }
+            return;
+        }
+        // 2. Interactive Flow Selection (Skip if --email flag is present)
+        let method = flags.email ? 'email' : null;
+        if (!method) {
+            if (this.isJsonMode) {
+                // In JSON mode without --token or --email, route to browser flow (which will output JSON)
+                await this.executeBrowserFlow(flags.local, flags.profile);
+                return;
+            }
+            method = await this.selectOption('How would you like to authenticate?', [
+                { label: 'Browser (Recommended)', value: 'browser', description: 'Open your browser to log in' },
+                { label: 'Email/Password', value: 'email', description: 'Enter your credentials in the terminal' },
+            ]);
+        }
+        if (!method)
+            return;
+        if (method === 'browser') {
+            await this.executeBrowserFlow(flags.local, flags.profile);
+        }
+        else {
+            await this.executeEmailFlow(flags.local, flags.profile);
+        }
+    }
+    async validateAndSave(opts) {
+        // Validate with cliAuthStatus before saving
+        const client = createApiClient({
+            baseUrl: getApiBaseUrl(),
+            credential: {
+                api_key: (opts.apiKey || opts.accessToken),
+                source: opts.local ? 'local' : 'global',
+                profile: opts.profile
+            },
+            isJsonMode: this.isJsonMode
+        });
+        const { error } = await cliAuthStatus({ client });
+        if (error) {
+            const detail = error.message || error.error?.message || 'API validation failed';
+            throw new Error(`Invalid credentials: ${detail}`);
+        }
+        await saveCredential(opts);
+    }
+    async executeBrowserFlow(local, profile) {
+        const state = generateState();
+        const { supabaseUrl, supabaseAnonKey } = getSupabaseConfig();
+        // Construct the login URL
+        const baseUrl = getApiBaseUrl();
+        const loginUrl = `${baseUrl}/api/cli/v1/auth/login?state=${state}`;
+        if (this.isJsonMode) {
+            this.outputJson({
+                url: loginUrl,
+                state,
+                message: 'Open the URL in your browser to complete authentication. The CLI will not wait for completion in JSON mode unless specifically requested (not implemented).'
+            });
+            return;
+        }
+        this.log('\nOpening your browser to authenticate...');
+        this.log(`URL: ${loginUrl}\n`);
+        const open = (await import('open')).default;
+        await open(loginUrl);
+        let result;
+        try {
+            result = await this.withSpinner('Waiting for authentication to complete...', () => subscribeForTokens({
+                supabaseUrl,
+                supabaseAnonKey,
+                state,
+            }));
+            const tokens = result.tokens;
+            await this.validateAndSave({
+                accessToken: tokens.access_token,
+                refreshToken: tokens.refresh_token,
+                expiresAt: tokens.expires_at,
+                user: tokens.user,
+                local,
+                profile,
+            });
+            if (this.isJsonMode) {
+                this.outputJson({
+                    message: 'Successfully authenticated via browser',
+                    user: tokens.user
+                });
+            }
+            else {
+                this.log('\nSuccessfully authenticated via browser!');
+            }
+        }
+        catch (error) {
+            if (this.isJsonMode) {
+                this.outputErrorAndExit(error);
+            }
+            else {
+                this.error(`Authentication failed: ${error.message}`);
+            }
+        }
+        finally {
+            result?.cleanup();
+        }
+    }
+    async executeEmailFlow(local, profile) {
+        if (this.isJsonMode) {
+            this.outputErrorAndExit({
+                message: 'Email authentication is not supported in JSON mode. Please use --token for headless authentication or run in non-JSON mode.',
+                code: 'INTERACTIVE_REQUIRED'
+            });
+        }
+        const email = await this.textInput('Email');
+        if (!email)
+            return;
+        const password = await this.textInput('Password', { mask: true });
+        if (!password)
+            return;
+        try {
+            const result = await this.withSpinner('Authenticating...', async () => {
+                return authenticateWithEmail({
+                    email,
+                    password,
+                    baseUrl: getApiBaseUrl(),
+                });
+            });
+            await this.validateAndSave({
+                accessToken: result.access_token,
+                refreshToken: result.refresh_token,
+                expiresAt: result.expires_at,
+                user: result.user,
+                local,
+                profile,
+            });
+            if (this.isJsonMode) {
+                this.outputJson({
+                    message: 'Successfully authenticated with email',
+                    user: result.user
+                });
+            }
+            else {
+                this.log('\nSuccessfully authenticated with email!');
+            }
+        }
+        catch (error) {
+            if (this.isJsonMode) {
+                this.outputErrorAndExit(error);
+            }
+            else {
+                this.error(`Authentication failed: ${error.message}`);
+            }
+        }
+    }
+}

package/dist/commands/auth/logout.js

@@ -0,0 +1,31 @@
+import { BaseCommand } from '../../base.js';
+import { Flags } from '@oclif/core';
+import { clearCredential, readCredentialsFile, getGlobalCredentialsPath, getLocalCredentialsPath } from '../../core/auth/credentials.js';
+export default class AuthLogout extends BaseCommand {
+    static description = 'Clear authentication credentials';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        profile: Flags.string({ description: 'Named profile to clear' }),
+        local: Flags.boolean({ description: 'Clear credentials from local project' }),
+    };
+    async run() {
+        const { flags } = await this.parse(AuthLogout);
+        await this.renderHeader('ready', 'compact');
+        // Determine which profile will be cleared for the output
+        const filePath = flags.local ? getLocalCredentialsPath() : getGlobalCredentialsPath();
+        const credentials = await readCredentialsFile(filePath);
+        const profileToClear = flags.profile ?? credentials?.active_profile ?? 'default';
+        try {
+            await clearCredential({ profile: flags.profile, local: flags.local });
+            if (this.isJsonMode) {
+                this.outputJson({ success: true, profile: profileToClear, location: flags.local ? 'local' : 'global' });
+            }
+            else {
+                this.log(`✓ Credentials cleared from ${flags.local ? 'local' : 'global'} profile '${profileToClear}'`);
+            }
+        }
+        catch (error) {
+            this.isJsonMode ? this.outputErrorAndExit(error.message) : this.error(error.message);
+        }
+    }
+}

package/dist/commands/auth/profile/delete.js

@@ -0,0 +1,34 @@
+import { BaseCommand } from '../../../base.js';
+import { Args } from '@oclif/core';
+import { deleteProfile } from '../../../core/auth/credentials.js';
+export default class AuthProfileDelete extends BaseCommand {
+    static description = 'Delete an authentication profile';
+    static args = {
+        name: Args.string({ description: 'Profile name to delete', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(AuthProfileDelete);
+        await this.renderHeader('ready', 'compact');
+        if (this.isDryRun) {
+            await this.handleDryRun({ action: 'delete_profile', name: args.name });
+            return;
+        }
+        try {
+            await deleteProfile(args.name);
+            if (this.isJsonMode) {
+                this.outputJson({ deleted_profile: args.name });
+            }
+            else {
+                this.log(`✓ Profile '${args.name}' deleted`);
+            }
+        }
+        catch (error) {
+            if (this.isJsonMode) {
+                this.outputErrorAndExit(error.message);
+            }
+            else {
+                this.error(error.message);
+            }
+        }
+    }
+}

package/dist/commands/auth/profile/list.js

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../../../base.js';
+import { listProfiles } from '../../../core/auth/credentials.js';
+import { ux } from '@oclif/core';
+export default class AuthProfileList extends BaseCommand {
+    static description = 'List authentication profiles';
+    async run() {
+        await this.renderHeader('ready', 'compact');
+        try {
+            const data = await listProfiles();
+            if (this.isJsonMode) {
+                this.outputJson(data);
+            }
+            else {
+                if (data.profiles.length === 0) {
+                    this.log('No profiles found.');
+                    return;
+                }
+                ux.stdout(data.profiles
+                    .map((p) => `${p.is_active ? '*' : ' '} ${p.name}`)
+                    .join('\n'));
+            }
+        }
+        catch (error) {
+            if (this.isJsonMode) {
+                this.outputErrorAndExit(error.message);
+            }
+            else {
+                this.error(error.message);
+            }
+        }
+    }
+}

package/dist/commands/auth/profile/use.js

@@ -0,0 +1,30 @@
+import { BaseCommand } from '../../../base.js';
+import { Args } from '@oclif/core';
+import { setActiveProfile } from '../../../core/auth/credentials.js';
+export default class AuthProfileUse extends BaseCommand {
+    static description = 'Set the active authentication profile';
+    static args = {
+        name: Args.string({ description: 'Profile name to activate', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(AuthProfileUse);
+        await this.renderHeader('ready', 'compact');
+        try {
+            await setActiveProfile(args.name);
+            if (this.isJsonMode) {
+                this.outputJson({ active_profile: args.name });
+            }
+            else {
+                this.log(`✓ Active profile set to '${args.name}'`);
+            }
+        }
+        catch (error) {
+            if (this.isJsonMode) {
+                this.outputErrorAndExit(error.message);
+            }
+            else {
+                this.error(error.message);
+            }
+        }
+    }
+}

package/dist/commands/auth/status.js

@@ -0,0 +1,107 @@
+import { BaseCommand } from '../../base.js';
+import { resolveCredential } from '../../core/auth/resolution.js';
+import { createApiClient, ConnectivityError } from '../../core/auth/api-client.js';
+import { ensureFreshToken } from '../../core/auth/token-refresh.js';
+import { cliAuthStatus } from '../../generated/api/sdk.gen.js';
+export default class AuthStatus extends BaseCommand {
+    static description = 'Check authentication status';
+    async run() {
+        const credential = await resolveCredential();
+        if (!credential) {
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({ message: 'Not authenticated', code: 'NO_CREDENTIALS' });
+            }
+            else {
+                this.log('Not authenticated. Run `4ge auth login --token <api_key>` to authenticate.');
+            }
+            return;
+        }
+        // Proactively refresh the token if it's expired/expiring.
+        // We do this BEFORE creating the API client so that we send a fresh token.
+        // We still use resolveCredential() + createApiClient() directly (instead of getClient())
+        // because auth:status wants to show raw credential state for diagnostics.
+        let freshCredential = null;
+        try {
+            freshCredential = await ensureFreshToken();
+        }
+        catch (refreshError) {
+            // Distinguish connectivity failures (server unreachable) from genuine
+            // session expiry (refresh token rejected). A dead server is NOT a
+            // session-expiry and must not be reported as one.
+            const isConnectivity = refreshError instanceof ConnectivityError;
+            const code = isConnectivity ? 'CONNECTION_ERROR' : 'SESSION_EXPIRED';
+            const message = isConnectivity
+                ? 'Cannot reach the 4ge API server to verify authentication.'
+                : 'Session expired. Token refresh failed.';
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({
+                    message,
+                    code,
+                    hint: refreshError.message || "Run '4ge auth login' to re-authenticate."
+                });
+            }
+            else {
+                if (isConnectivity) {
+                    this.log('⚠ Cannot reach the 4ge API server — token could not be refreshed.');
+                }
+                else {
+                    this.log('⚠ Session expired — token refresh failed.');
+                }
+                this.log(`  ${refreshError.message || "Run '4ge auth login' to re-authenticate."}`);
+            }
+            return;
+        }
+        // Use the fresh credential if available, otherwise fall back to the originally resolved one
+        const activeCredential = freshCredential || credential;
+        try {
+            if (!this.isJsonMode) {
+                await this.renderHeader('ready', 'compact');
+            }
+            const client = createApiClient({ credential: activeCredential, isJsonMode: this.isJsonMode });
+            const { data, error } = await cliAuthStatus({ client });
+            if (error) {
+                if (this.isJsonMode) {
+                    if (activeCredential.source === 'environment') {
+                        this.outputErrorAndExit({
+                            message: 'API validation failed for 4GE_API_KEY',
+                            code: 'ENV_CREDENTIAL_OVERRIDE',
+                            hint: 'The 4GE_API_KEY environment variable is overriding stored credentials but is invalid. Unset it to use credentials from "4ge auth login".'
+                        });
+                    }
+                    else {
+                        this.outputErrorAndExit({ message: 'API validation failed', code: 'VALIDATION_FAILED' });
+                    }
+                }
+                else {
+                    if (activeCredential.source === 'environment') {
+                        this.log('⚠ Using API key from 4GE_API_KEY environment variable, but server validation failed.');
+                        this.log('');
+                        this.log('The 4GE_API_KEY environment variable takes priority over stored credentials.');
+                        this.log('FIX: Unset 4GE_API_KEY (e.g., `unset 4GE_API_KEY`) to use credentials from `4ge auth login`.');
+                    }
+                    else {
+                        this.log(`Authenticated via ${activeCredential.source}${activeCredential.profile ? ` (profile: ${activeCredential.profile})` : ''}, but API validation failed.`);
+                    }
+                }
+                return;
+            }
+            if (this.isJsonMode) {
+                this.outputJson({ source: activeCredential.source, profile: activeCredential.profile, user: data });
+            }
+            else {
+                if (activeCredential.source === 'environment') {
+                    this.log('ℹ Authenticated via 4GE_API_KEY environment variable (overrides stored credentials).');
+                }
+                this.log('Authenticated');
+                this.log(`Source:  ${activeCredential.source}`);
+                if (activeCredential.profile)
+                    this.log(`Profile: ${activeCredential.profile}`);
+                if (data)
+                    this.log(`User:    ${data.email || data.id || 'Unknown'}`);
+            }
+        }
+        catch (error) {
+            this.isJsonMode ? this.outputErrorAndExit(error.message) : this.error(error.message);
+        }
+    }
+}

package/dist/commands/config/get.js

@@ -0,0 +1,37 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { readConfig } from '../../core/config/parser.js';
+export default class ConfigGet extends BaseCommand {
+    static description = 'Get a configuration value';
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    static args = {
+        key: Args.string({ description: 'Config key (dot notation, e.g., cli.default_mode)', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(ConfigGet);
+        const config = await readConfig();
+        if (!config) {
+            this.handleError('No project config found. Run `4ge init` first.', { code: 'NOT_INITIALIZED' });
+            return;
+        }
+        await this.renderHeader('ready', 'compact');
+        const value = this.getDotNotationValue(config, args.key);
+        if (this.isJsonMode) {
+            this.outputJson({ key: args.key, value: value ?? null });
+            return;
+        }
+        if (value === undefined || value === null) {
+            this.log(`Key '${args.key}' not found in configuration.`);
+        }
+        else {
+            this.log(String(value));
+        }
+    }
+    getDotNotationValue(obj, path) {
+        return path.split('.').reduce((prev, curr) => {
+            return prev ? prev[curr] : undefined;
+        }, obj);
+    }
+}

package/dist/commands/config/index.js

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class ConfigIndex extends Command {
+    static description = 'Manage CLI configuration';
+    static hidden = true;
+    async run() {
+        this.log('Use `4ge config manage` for interactive configuration.');
+        this.log('Use `4ge config show`, `4ge config get`, or `4ge config set` for direct access.');
+    }
+}

package/dist/commands/config/manage.js

@@ -0,0 +1,165 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { BaseCommand } from '../../base.js';
+import { readConfig, writeConfig } from '../../core/config/parser.js';
+import { ProjectConfigSchema } from '../../core/config/schema.js';
+import { SuccessMessage } from '../../ui/components/success-message.js';
+const FIELDS = [
+    // Project Section
+    {
+        key: 'project_id',
+        label: 'Project ID',
+        type: 'string',
+        getValue: (c) => c.project_id,
+        setValue: (c, v) => ({ ...c, project_id: v }),
+    },
+    {
+        key: 'workspace_id',
+        label: 'Workspace ID',
+        type: 'string',
+        getValue: (c) => c.workspace_id,
+        setValue: (c, v) => ({ ...c, workspace_id: v }),
+    },
+    {
+        key: 'project_name',
+        label: 'Project Name',
+        type: 'string',
+        getValue: (c) => c.project_name,
+        setValue: (c, v) => ({ ...c, project_name: v }),
+    },
+    {
+        key: 'workspace_name',
+        label: 'Workspace Name',
+        type: 'string',
+        getValue: (c) => c.workspace_name,
+        setValue: (c, v) => ({ ...c, workspace_name: v }),
+    },
+    // Hierarchy Section
+    {
+        key: 'hierarchy.default_roadmap_filter',
+        label: 'Default Roadmap Filter',
+        type: 'enum',
+        options: ['now', 'next', 'later', 'all'],
+        getValue: (c) => c.hierarchy.default_roadmap_filter,
+        setValue: (c, v) => ({ ...c, hierarchy: { ...c.hierarchy, default_roadmap_filter: v } }),
+    },
+    {
+        key: 'hierarchy.recursive_pull',
+        label: 'Recursive Pull',
+        type: 'boolean',
+        getValue: (c) => c.hierarchy.recursive_pull,
+        setValue: (c, v) => ({ ...c, hierarchy: { ...c.hierarchy, recursive_pull: v } }),
+    },
+    // Pull Section
+    {
+        key: 'pull.generate_stubs',
+        label: 'Generate Stubs',
+        type: 'boolean',
+        getValue: (c) => c.pull.generate_stubs,
+        setValue: (c, v) => ({ ...c, pull: { ...c.pull, generate_stubs: v } }),
+    },
+    {
+        key: 'pull.include_brief_deps',
+        label: 'Include Brief Deps',
+        type: 'boolean',
+        getValue: (c) => c.pull.include_brief_deps,
+        setValue: (c, v) => ({ ...c, pull: { ...c.pull, include_brief_deps: v } }),
+    },
+    // CLI Section
+    {
+        key: 'cli.default_mode',
+        label: 'Default Mode',
+        type: 'enum',
+        options: ['pretty', 'interactive'],
+        getValue: (c) => c.cli.default_mode,
+        setValue: (c, v) => ({ ...c, cli: { ...c.cli, default_mode: v } }),
+    },
+];
+const SECTIONS = [
+    { label: 'Project Identity', value: 'project', keys: ['project_id', 'workspace_id', 'project_name', 'workspace_name'] },
+    { label: 'Hierarchy', value: 'hierarchy', keys: ['hierarchy.default_roadmap_filter', 'hierarchy.recursive_pull'] },
+    { label: 'Pull', value: 'pull', keys: ['pull.generate_stubs', 'pull.include_brief_deps'] },
+    { label: 'CLI', value: 'cli', keys: ['cli.default_mode'] },
+];
+export default class ConfigManage extends BaseCommand {
+    static description = 'Interactive configuration management TUI';
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    async run() {
+        const config = await readConfig();
+        if (!config) {
+            this.error('No configuration found. Run `4ge init` first.');
+        }
+        await this.renderHeader('ready');
+        if (this.isJsonMode) {
+            this.outputJson(config);
+            return;
+        }
+        while (true) {
+            const sectionValue = await this.selectOption('Select a section to edit:', [
+                ...SECTIONS,
+                { label: 'Done ← Exit', value: 'done' },
+            ], {
+                helpText: 'Esc: exit • Ctrl+D: exit'
+            });
+            if (sectionValue === 'done')
+                break;
+            const section = SECTIONS.find(s => s.value === sectionValue);
+            const sectionFields = FIELDS.filter(f => section.keys.includes(f.key));
+            while (true) {
+                const currentConfig = await readConfig();
+                if (!currentConfig)
+                    break;
+                const fieldKey = await this.selectOption(`Edit ${section.label} settings:`, [
+                    ...sectionFields.map(f => ({
+                        label: `${f.label}: ${f.getValue(currentConfig)}`,
+                        value: f.key,
+                    })),
+                    { label: '← Back', value: 'back' },
+                ], {
+                    helpText: 'Esc: back • Ctrl+D: exit'
+                });
+                if (fieldKey === 'back')
+                    break;
+                const field = sectionFields.find(f => f.key === fieldKey);
+                const newValue = await this.promptForValue(field, field.getValue(currentConfig));
+                if (newValue === undefined || newValue === null)
+                    continue;
+                try {
+                    const updatedConfig = field.setValue(currentConfig, newValue);
+                    const validated = ProjectConfigSchema.parse(updatedConfig);
+                    await writeConfig(validated);
+                    await this.renderInk(_jsx(SuccessMessage, { message: `Updated ${field.label}` }));
+                }
+                catch (error) {
+                    this.warn(`Failed to update ${field.label}: ${error.message}`);
+                }
+            }
+        }
+        await this.renderInk(_jsx(SuccessMessage, { message: "Configuration saved" }));
+    }
+    async promptForValue(field, currentValue) {
+        if (field.type === 'enum') {
+            const choice = await this.selectOption(`Edit ${field.label} (current: ${currentValue})`, [
+                ...field.options.map(o => ({ label: o, value: o })),
+                { label: 'Cancel', value: 'cancel' },
+            ], {
+                helpText: 'Esc: cancel • Ctrl+D: exit'
+            });
+            return choice === 'cancel' ? undefined : choice;
+        }
+        if (field.type === 'boolean') {
+            const choice = await this.selectOption(`Edit ${field.label} (current: ${currentValue})`, [
+                { label: 'true', value: 'true' },
+                { label: 'false', value: 'false' },
+                { label: 'Cancel', value: 'cancel' },
+            ], {
+                helpText: 'Esc: cancel • Ctrl+D: exit'
+            });
+            return choice === 'cancel' ? undefined : choice === 'true';
+        }
+        if (field.type === 'string') {
+            return this.textInput(field.label, { defaultValue: currentValue || '' });
+        }
+    }
+}