feedbackbasket-cli 0.3.0

package/README.md

@@ -0,0 +1,215 @@
+# FeedbackBasket CLI
+
+Command-line interface for [FeedbackBasket](https://feedbackbasket.com) — manage feedback, bug reports, projects, and widgets from your terminal or through AI agents.
+
+Inspired by the [Basecamp CLI](https://github.com/basecamp/basecamp-cli). Everything you can do in the dashboard, you can do from the CLI.
+
+## Quick Start
+
+```bash
+# Install
+npm install -g feedbackbasket-cli
+
+# Authenticate (opens browser, full access by default)
+feedbackbasket login
+
+# Or use a token directly (for CI/headless)
+feedbackbasket login --token fb_cli_your_token_here
+
+# Start exploring
+feedbackbasket projects list
+feedbackbasket feedback list
+feedbackbasket bugs list --severity high
+```
+
+The first time you log in, a setup wizard walks you through selecting a default project and installing the Claude Code skill.
+
+## Agent Usage
+
+Any AI agent with shell access (Claude Code, Codex, Cursor, OpenCode) can use the CLI directly:
+
+```bash
+# Agents should use --agent flag for raw JSON output
+feedbackbasket projects list --agent
+feedbackbasket feedback list --category BUG --agent
+feedbackbasket feedback update <id> --status PLANNED --agent
+feedbackbasket widget script myproject --agent
+```
+
+### Install Claude Code Skill
+
+```bash
+feedbackbasket setup claude
+```
+
+## Commands
+
+### Authentication
+
+```bash
+feedbackbasket login                   # Browser OAuth flow (alias for auth login)
+feedbackbasket login --token <token>   # Manual token (CI/headless)
+feedbackbasket logout                  # Clear credentials (alias for auth logout)
+feedbackbasket auth status             # Show auth state, scope, default project
+feedbackbasket auth token              # Print raw token (for scripting/piping)
+```
+
+### Projects
+
+All project commands accept **name or ID** (e.g. `feedbackbasket` or `cmn3c7sgv...`).
+
+```bash
+feedbackbasket projects list                              # List all projects with stats
+feedbackbasket projects show <name-or-id>                 # Project details
+feedbackbasket projects create "My App" --url https://... # Create project
+feedbackbasket projects update myapp --name "New Name"    # Update project
+feedbackbasket projects delete myapp                      # Delete (with confirmation)
+```
+
+### Feedback
+
+```bash
+# Read
+feedbackbasket feedback list                              # List recent feedback
+feedbackbasket feedback list --project myapp              # Filter by project
+feedbackbasket feedback list --category BUG               # Filter by category
+feedbackbasket feedback list --status OPEN                # Filter by status
+feedbackbasket feedback list --sentiment NEGATIVE          # Filter by sentiment
+feedbackbasket feedback list --search "login issue"        # Text search
+feedbackbasket feedback show <id>                          # View single item detail
+feedbackbasket feedback search "crash on mobile"           # Search shortcut
+
+# Write
+feedbackbasket feedback update <id> --status PLANNED       # Update status
+feedbackbasket feedback update <id> --category BUG         # Update category
+feedbackbasket feedback note <id> "Investigating this..."  # Add internal note
+feedbackbasket feedback delete <id>                        # Delete feedback
+feedbackbasket feedback bulk-update --status CLOSED --ids id1,id2,id3
+
+# Export
+feedbackbasket feedback export myapp --format csv          # Export to CSV
+feedbackbasket feedback export myapp --format md           # Export to Markdown
+feedbackbasket feedback export myapp --format json         # Export to JSON
+```
+
+### Bug Reports
+
+```bash
+feedbackbasket bugs list                    # All bugs
+feedbackbasket bugs list --severity high    # High severity only
+feedbackbasket bugs list --status OPEN      # Open bugs
+feedbackbasket bugs stats                   # Bug statistics summary
+feedbackbasket bugs stats --project myapp   # Per-project stats
+```
+
+### Widget
+
+```bash
+# View current settings
+feedbackbasket widget settings myapp
+
+# Update widget configuration
+feedbackbasket widget settings myapp --color "#22c55e" --label "Send Feedback"
+feedbackbasket widget settings myapp --position bottom-left --display modal
+feedbackbasket widget settings myapp --email-required --intro "How can we improve?"
+
+# Get embed code (ready to paste into your HTML)
+feedbackbasket widget script myapp
+```
+
+### Team
+
+```bash
+feedbackbasket team list                          # List organization members
+feedbackbasket team role <memberId> --role admin   # Update member role
+feedbackbasket team remove <memberId>              # Remove member
+```
+
+### Utilities
+
+```bash
+feedbackbasket doctor         # Run diagnostics (auth, connectivity, integrations)
+feedbackbasket setup claude   # Install Claude Code skill
+```
+
+## Output Modes
+
+The CLI automatically detects your environment:
+
+| Context | Behavior |
+|---------|----------|
+| **Terminal (TTY)** | Styled, human-readable output with FeedbackBasket brand colors |
+| **Piped** | JSON output automatically |
+| `--json` | Full JSON envelope with breadcrumbs |
+| `--quiet` / `--agent` | Raw JSON data only (no envelope) |
+| `--md` | Markdown formatted |
+
+### JSON Envelope
+
+```json
+{
+  "ok": true,
+  "data": [...],
+  "summary": "12 open bugs, 3 high severity",
+  "breadcrumbs": [
+    { "action": "View high severity", "cmd": "feedbackbasket bugs list --severity high" }
+  ]
+}
+```
+
+Breadcrumbs suggest the next logical command — useful for both humans and agents navigating without a full command catalog.
+
+## Configuration
+
+Credentials stored in `~/.config/feedbackbasket/credentials.json`. Config in `~/.config/feedbackbasket/config.json`.
+
+### Default Project
+
+Set during the login wizard, or manually:
+
+```bash
+# Commands auto-scope to your default project
+feedbackbasket feedback list        # uses default project
+feedbackbasket feedback list --project other-app  # override
+```
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FEEDBACKBASKET_TOKEN` | CLI token (bypasses stored credentials) |
+| `FEEDBACKBASKET_BASE_URL` | API base URL override |
+
+### Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Full JSON envelope output |
+| `--quiet` / `--agent` | Raw JSON data only |
+| `--md` | Markdown output |
+| `--base-url <url>` | Override API base URL |
+
+## Filter Options
+
+| Type | Values |
+|------|--------|
+| **Categories** | `BUG`, `FEATURE_REQUEST`, `IMPROVEMENT`, `QUESTION` |
+| **Statuses** | `OPEN`, `UNDER_REVIEW`, `PLANNED`, `IN_PROGRESS`, `COMPLETE`, `CLOSED` |
+| **Sentiments** | `POSITIVE`, `NEGATIVE`, `NEUTRAL` |
+| **Bug Severity** | `high`, `medium`, `low` |
+
+## Development
+
+```bash
+git clone https://github.com/deifos/feedbackbasket-cli.git
+cd feedbackbasket-cli
+npm install
+npm run dev -- --help         # Run in development
+npm run build                 # Build for production
+npm run dev -- login          # Test login flow
+npm run dev -- doctor         # Test diagnostics
+```
+
+## License
+
+MIT

package/dist/bin/feedbackbasket.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/feedbackbasket.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run();

package/dist/src/auth/login.d.ts

@@ -0,0 +1,6 @@
+interface LoginResult {
+    token: string;
+    scope: 'read' | 'full';
+}
+export declare function browserLogin(baseUrl: string, scope?: 'read' | 'full'): Promise<LoginResult>;
+export {};

package/dist/src/auth/login.js

@@ -0,0 +1,111 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { URL } from 'node:url';
+import open from 'open';
+import { brand, logo } from '../output/theme.js';
+const TIMEOUT_MS = 120_000;
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html><head><title>FeedbackBasket CLI</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    display: flex; align-items: center; justify-content: center; min-height: 100vh;
+    margin: 0; background: #0a0a0a; color: #fafafa; }
+  .card { text-align: center; max-width: 400px; padding: 3rem; }
+  h1 { color: #22c55e; font-size: 1.5rem; }
+  p { color: #a1a1aa; line-height: 1.6; }
+</style></head>
+<body><div class="card">
+  <h1>Authenticated!</h1>
+  <p>You can close this window and return to your terminal.</p>
+</div></body></html>`;
+const ERROR_HTML = (message) => `<!DOCTYPE html>
+<html><head><title>FeedbackBasket CLI</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    display: flex; align-items: center; justify-content: center; min-height: 100vh;
+    margin: 0; background: #0a0a0a; color: #fafafa; }
+  .card { text-align: center; max-width: 400px; padding: 3rem; }
+  h1 { color: #ef4444; font-size: 1.5rem; }
+  p { color: #a1a1aa; line-height: 1.6; }
+</style></head>
+<body><div class="card">
+  <h1>Authentication Failed</h1>
+  <p>${message}</p>
+</div></body></html>`;
+export async function browserLogin(baseUrl, scope = 'read') {
+    const state = randomUUID();
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', `http://127.0.0.1`);
+            if (url.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const receivedState = url.searchParams.get('state');
+            const token = url.searchParams.get('token');
+            const error = url.searchParams.get('error');
+            // CSRF validation
+            if (receivedState !== state) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(ERROR_HTML('State mismatch — possible CSRF attack. Please try again.'));
+                cleanup();
+                reject(new Error('State mismatch during authentication'));
+                return;
+            }
+            // User denied
+            if (error) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(ERROR_HTML(`Authorization was denied: ${error}`));
+                cleanup();
+                reject(new Error(`Authorization denied: ${error}`));
+                return;
+            }
+            // Missing token
+            if (!token) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(ERROR_HTML('No token received. Please try again.'));
+                cleanup();
+                reject(new Error('No token received in callback'));
+                return;
+            }
+            // Success
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(SUCCESS_HTML);
+            cleanup();
+            resolve({ token, scope });
+        });
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error('Authentication timed out after 2 minutes'));
+        }, TIMEOUT_MS);
+        function cleanup() {
+            clearTimeout(timeout);
+            server.close();
+        }
+        // Listen on random port on loopback
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (!addr || typeof addr === 'string') {
+                cleanup();
+                reject(new Error('Failed to start local auth server'));
+                return;
+            }
+            const port = addr.port;
+            const authorizeUrl = `${baseUrl}/cli/authorize?callback_port=${port}&state=${state}&scope=${scope}`;
+            console.log();
+            console.log(`  ${logo()} CLI`);
+            console.log();
+            console.log(`  ${brand.primary('Opening browser for authentication...')}`);
+            console.log();
+            console.log(`  ${brand.muted('If the browser doesn\'t open, visit:')}`);
+            console.log(`  ${brand.primary(authorizeUrl)}`);
+            console.log();
+            console.log(`  ${brand.muted('Waiting for authentication...')}`);
+            console.log();
+            open(authorizeUrl).catch(() => {
+                // Browser open failed — user will use the URL manually
+            });
+        });
+    });
+}

package/dist/src/auth/manager.d.ts

@@ -0,0 +1,11 @@
+import { type Credentials } from '../config/credentials.js';
+export declare class AuthManager {
+    private credentials;
+    private loaded;
+    resolveToken(): string | null;
+    isAuthenticated(): boolean;
+    getCredentials(): Credentials | null;
+    getTokenPreview(): string | null;
+    getSource(): 'env' | 'file' | null;
+    logout(): void;
+}

package/dist/src/auth/manager.js

@@ -0,0 +1,38 @@
+import { loadCredentials, clearCredentials, maskToken } from '../config/credentials.js';
+export class AuthManager {
+    credentials = null;
+    loaded = false;
+    resolveToken() {
+        const creds = this.getCredentials();
+        return creds?.token ?? null;
+    }
+    isAuthenticated() {
+        return this.resolveToken() !== null;
+    }
+    getCredentials() {
+        if (!this.loaded) {
+            this.credentials = loadCredentials();
+            this.loaded = true;
+        }
+        return this.credentials;
+    }
+    getTokenPreview() {
+        const creds = this.getCredentials();
+        if (!creds)
+            return null;
+        return maskToken(creds.token);
+    }
+    getSource() {
+        if (process.env['FEEDBACKBASKET_TOKEN'])
+            return 'env';
+        const creds = this.getCredentials();
+        if (creds)
+            return 'file';
+        return null;
+    }
+    logout() {
+        clearCredentials();
+        this.credentials = null;
+        this.loaded = false;
+    }
+}

package/dist/src/cli.d.ts

@@ -0,0 +1 @@
+export declare function run(): void;

package/dist/src/cli.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import { VERSION } from './version.js';
+import { OutputWriter, Format } from './output/writer.js';
+import { CLIError } from './output/errors.js';
+import { setBaseUrlOverride } from './config/config.js';
+import { createAuthCommand, createLoginCommand, createLogoutCommand } from './commands/auth.js';
+import { createProjectsCommand } from './commands/projects.js';
+import { createFeedbackCommand } from './commands/feedback.js';
+import { createBugsCommand } from './commands/bugs.js';
+import { createDoctorCommand } from './commands/doctor.js';
+import { createSetupCommand } from './commands/setup.js';
+import { createWidgetCommand } from './commands/widget.js';
+import { createTeamCommand } from './commands/team.js';
+let writer;
+function resolveFormat(opts) {
+    if (opts.agent || opts.quiet)
+        return Format.Quiet;
+    if (opts.json)
+        return Format.JSON;
+    if (opts.md)
+        return Format.Markdown;
+    return Format.Auto;
+}
+function getWriter() {
+    return writer;
+}
+export function run() {
+    const program = new Command('feedbackbasket')
+        .version(VERSION, '-v, --version')
+        .description('Command-line interface for FeedbackBasket')
+        .option('--json', 'Output as JSON envelope')
+        .option('--quiet', 'Output raw data only (no envelope)')
+        .option('--agent', 'Agent mode (alias for --quiet)')
+        .option('--md', 'Output as Markdown')
+        .option('--base-url <url>', 'API base URL override')
+        .hook('preAction', (thisCommand) => {
+        const opts = thisCommand.opts();
+        const format = resolveFormat(opts);
+        writer = new OutputWriter({ format });
+        if (opts.baseUrl) {
+            setBaseUrlOverride(opts.baseUrl);
+        }
+    });
+    // Register commands
+    program.addCommand(createAuthCommand(getWriter));
+    program.addCommand(createLoginCommand(getWriter)); // alias: feedbackbasket login
+    program.addCommand(createLogoutCommand(getWriter)); // alias: feedbackbasket logout
+    program.addCommand(createProjectsCommand(getWriter));
+    program.addCommand(createFeedbackCommand(getWriter));
+    program.addCommand(createBugsCommand(getWriter));
+    program.addCommand(createWidgetCommand(getWriter));
+    program.addCommand(createTeamCommand(getWriter));
+    program.addCommand(createDoctorCommand(getWriter));
+    program.addCommand(createSetupCommand(getWriter));
+    // Global error handler
+    program.exitOverride();
+    (async () => {
+        try {
+            await program.parseAsync(process.argv);
+        }
+        catch (error) {
+            if (error instanceof CLIError) {
+                if (!writer) {
+                    writer = new OutputWriter({ format: Format.Auto });
+                }
+                writer.err(error);
+                process.exit(error.exitCode);
+            }
+            // Commander's own errors (help, version, etc.)
+            if (error instanceof Error && 'exitCode' in error) {
+                const exitCode = error.exitCode;
+                process.exit(exitCode);
+            }
+            // Unknown errors
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    })();
+}

package/dist/src/client.d.ts

@@ -0,0 +1,105 @@
+import type { ProjectsResponse, FeedbackResponse, BugReportsResponse, FeedbackParams, BugReportParams, UserProfile, Project, Feedback } from './types.js';
+export declare class FeedbackBasketClient {
+    private http;
+    constructor(token: string, baseUrl: string);
+    me(): Promise<UserProfile>;
+    listProjects(): Promise<ProjectsResponse>;
+    getProject(id: string): Promise<Project>;
+    createProject(data: {
+        name: string;
+        url: string;
+        description?: string;
+    }): Promise<{
+        project: Project;
+    }>;
+    updateProject(id: string, data: {
+        name?: string;
+        url?: string;
+        description?: string;
+    }): Promise<Project>;
+    deleteProject(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+        name: string;
+    }>;
+    getFeedback(params?: FeedbackParams): Promise<FeedbackResponse>;
+    getFeedbackById(id: string): Promise<Feedback>;
+    getBugReports(params?: BugReportParams): Promise<BugReportsResponse>;
+    getBugStats(params?: {
+        projectId?: string;
+    }): Promise<BugReportsResponse['stats']>;
+    searchFeedback(query: string, opts?: {
+        projectId?: string;
+        category?: string;
+        limit?: number;
+    }): Promise<FeedbackResponse>;
+    getWidgetSettings(projectId: string): Promise<{
+        projectId: string;
+        projectName: string;
+        settings: Record<string, unknown>;
+    }>;
+    updateWidgetSettings(projectId: string, settings: Record<string, unknown>): Promise<{
+        projectId: string;
+        projectName: string;
+        settings: Record<string, unknown>;
+    }>;
+    getWidgetScript(projectId: string): Promise<{
+        projectId: string;
+        projectName: string;
+        embedCode: string;
+        scriptUrl: string;
+    }>;
+    updateFeedback(id: string, data: {
+        status?: string;
+        category?: string;
+        sentiment?: string;
+    }): Promise<Feedback>;
+    createNote(feedbackId: string, content: string): Promise<{
+        id: string;
+        content: string;
+        createdAt: string;
+    }>;
+    deleteFeedback(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    bulkUpdateStatus(ids: string[], status: string): Promise<{
+        updated: number;
+        status: string;
+    }>;
+    updateNote(feedbackId: string, noteId: string, content: string): Promise<{
+        id: string;
+        content: string;
+        createdAt: string;
+    }>;
+    deleteNote(feedbackId: string, noteId: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    exportFeedback(projectId: string, format?: 'csv' | 'md' | 'json'): Promise<string>;
+    listTeam(): Promise<{
+        members: Array<{
+            memberId: string;
+            userId: string;
+            name: string;
+            email: string;
+            role: string;
+            joinedAt: string;
+        }>;
+        totalMembers: number;
+    }>;
+    updateMemberRole(memberId: string, role: string): Promise<{
+        memberId: string;
+        name: string;
+        email: string;
+        role: string;
+    }>;
+    removeMember(memberId: string): Promise<{
+        removed: boolean;
+        memberId: string;
+        name: string;
+        email: string;
+    }>;
+    private request;
+    private handleError;
+}