npm package: @makeitvisible/cli
Description: CLI for code analysis and artifact generation - Transform technical changes into audience-friendly materials
Author: Visible Team
Latest version: 0.2.0

# @visible/cli

Transform technical changes into audience-friendly communication materials.

The Visible CLI helps technical teams analyze code, PRs, and repositories to generate artifacts that can be used for documentation, release notes, tutorials, and more.

## Features

- **Git Diff Analysis**: Analyze git diffs between commits to extract context and generate artifacts
- **Pull Request Analysis**: Analyze GitHub PRs with automatic context extraction
- **AI-Powered Code Exploration**: Use "The Detective" agent to intelligently explore and understand codebases
- **Artifact Generation**: Create structured artifacts ready for documentation generation
- **Video Generation**: Automatically generate professional tutorial and release videos from your code

## Installation

```bash
# Install globally from npm
npm install -g @visible/cli

# Or use npx to run without installing
npx @visible/cli --help
```

## Quick Start

```bash
# Get help
visible --help

# Analyze the latest commit
visible analyze diff

# Analyze a specific commit range
visible analyze diff HEAD~5..HEAD

# Analyze a pull request
visible analyze pr --url https://github.com/owner/repo/pull/123

# Explore a codebase with AI
visible analyze prompt "how does user authentication work"
```

## Configuration

The CLI requires the following environment variables:

```bash
# Required for AI-powered code exploration (analyze prompt)
export OPENAI_API_KEY=sk-your-openai-api-key

# Required for posting artifacts to Visible API
# For local dev, defaults to http://localhost:3000/api and no API key is required
export VISIBLE_API_BASE_URL=https://your-visible-instance.com
export VISIBLE_API_KEY=your-api-key

# Optional: For PR analysis via GitHub API
export GITHUB_TOKEN=ghp-your-github-token
```

You can set these in your shell profile (`.bashrc`, `.zshrc`, etc.) or use a `.env` file with a tool like [direnv](https://direnv.net/).

## Commands

### `visible analyze diff [range]`

Analyze git diff between commits to create an artifact.

```bash
# Analyze the latest commit
visible analyze diff

# Analyze a specific range
visible analyze diff HEAD~5..HEAD

# Skip posting to API (just preview the artifact)
visible analyze diff --no-post
```

**Options:**
- `[range]` - Git commit range (default: `HEAD~1..HEAD`)
- `--no-post` - Skip posting artifact to Visible API
- `--video [path]` - Generate video (optional: output directory)
- `--video-format <format>` - Video format: `mp4` or `webm`
- `--video-resolution <res>` - Resolution: `1080p`, `720p`, `480p`, `square`, `vertical`

### `visible analyze pr`

Analyze a pull request to create an artifact.

```bash
# Analyze by PR URL
visible analyze pr --url https://github.com/owner/repo/pull/123

# Analyze by PR number (uses current repo)
visible analyze pr --number 123

# Skip posting to API
visible analyze pr --url https://github.com/owner/repo/pull/123 --no-post
```

**Options:**
- `--url <url>` - Pull request URL
- `--number <number>` - Pull request number (uses current repo)
- `--no-post` - Skip posting artifact to Visible API
- `--video [path]` - Generate video (optional: output directory)
- `--video-format <format>` - Video format: `mp4` or `webm`
- `--video-resolution <res>` - Resolution: `1080p`, `720p`, `480p`, `square`, `vertical`

### `visible analyze prompt "<query>"`

Explore your codebase with an AI agent (The Detective) that intelligently navigates files, follows imports, and understands code relationships.

```bash
# Explore a feature
visible analyze prompt "how does user authentication work"

# Understand a specific flow
visible analyze prompt "explain the payment processing flow"

# Document an API endpoint
visible analyze prompt "describe the /api/users endpoint"

# Verbose mode to see agent's reasoning
visible analyze prompt "payment processing flow" --verbose

# Skip posting to API
visible analyze prompt "explain the search feature" --no-post
```

**Options:**
- `<query>` - Natural language prompt describing what to analyze
- `-v, --verbose` - Show detailed agent activity
- `--no-post` - Skip posting artifact to Visible API
- `--video [path]` - Generate video (optional: output directory)
- `--video-format <format>` - Video format: `mp4` or `webm`
- `--video-resolution <res>` - Resolution: `1080p`, `720p`, `480p`, `square`, `vertical`

**How The Detective Agent works:**

1. Searches for files related to your query
2. Reads relevant files and follows imports
3. Finds where components/functions are used (entry points)
4. Traces data flow through the codebase
5. Identifies key data structures and schemas
6. Produces a structured artifact with:
   - Entry points (how the feature is triggered)
   - Data flow (step-by-step explanation)
   - Key files and their purposes
   - Data structures involved
   - Usage examples from the codebase

## Video Generation

Generate professional videos that showcase your features, explain changes, or create tutorials.

```bash
# Generate a video from feature analysis
visible analyze prompt "how does checkout work" --video

# Generate a video from git changes
visible analyze diff --video

# Customize resolution and format
visible analyze pr --url https://github.com/org/repo/pull/123 \
  --video ./videos \
  --video-resolution 1080p \
  --video-format mp4
```

**Resolution presets:** `1080p`, `720p`, `480p`, `square` (Instagram), `vertical` (TikTok/Stories)

Videos include:
- AI-generated UI mockups matching your app's design
- Code highlights with syntax highlighting
- Professional transitions and animations
- Your color scheme and branding

See [docs/VIDEO-GENERATION.md](docs/VIDEO-GENERATION.md) for the complete guide.

## Example Workflow

```bash
# 1. Navigate to your project
cd your-project

# 2. Set up environment
export OPENAI_API_KEY=sk-xxx
export VISIBLE_API_BASE_URL=http://localhost:3000
# API key is optional when using localhost
export VISIBLE_API_KEY=my-key

# 3. Explore a feature and create an artifact
visible analyze prompt "how do users create new projects"

# 4. The CLI will output:
#    - Investigation results (entry points, data flow, key files)
#    - Post the artifact to the Visible API
#    - Return a URL to continue in the dashboard

# 5. Generate a video (optional)
visible analyze prompt "how do users create new projects" --video
```

## Artifact Output

All commands generate artifacts with the following structure:

```typescript
interface Artifact {
  title: string;
  description: string;
  source: {
    type: "pr" | "commit" | "code-section" | "repository";
    reference: string;
    url?: string;
  };
  context: {
    summary: string;
    technicalDetails: string[];
    affectedComponents: string[];
    breakingChanges: boolean;
    keywords: string[];
  };
  guidelines: string[];
}
```

## Programmatic Usage

You can also use the CLI as a library:

```typescript
import { analyzeDiff, analyzePR, investigateFeature } from "@visible/cli";

// Analyze a git diff
const diffResult = await analyzeDiff("HEAD~1..HEAD");

// Analyze a PR
const prResult = await analyzePR({ url: "https://github.com/org/repo/pull/123" });

// Investigate a feature
const investigation = await investigateFeature("how does authentication work", {
  verbose: true,
  onToolCall: (name, args) => console.log(`Tool: ${name}`),
});
```

## Requirements

- Node.js >= 20
- Git (for diff/PR analysis)
- OpenAI API key (for AI-powered exploration)
- GitHub CLI (`gh`) for PR analysis (optional but recommended)

## Troubleshooting

### "Missing OPENAI_API_KEY"

Set the `OPENAI_API_KEY` environment variable with your OpenAI API key.

### "Not in a git repository"

Make sure you're running the CLI from within a git repository.

### PR analysis fails

Ensure you have the GitHub CLI (`gh`) installed and authenticated:
```bash
gh auth login
```

## License

MIT

## Contributing

See the main [Visible repository](https://github.com/your-org/visible) for contribution guidelines.