@makeitvisible/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-24
+
+### Added
+
+- Initial release of `@visible/cli`
+- `visible analyze diff` command for git diff analysis
+- `visible analyze pr` command for pull request analysis
+- `visible analyze prompt` command for AI-powered codebase exploration
+- "The Detective" AI agent for intelligent code navigation
+- Artifact generation with structured output
+- Support for posting artifacts to Visible API
+- Programmatic API for library usage
+
+### Features
+
+- Git diff analysis with automatic breaking change detection
+- Pull request analysis with GitHub CLI integration
+- AI-powered codebase exploration using OpenAI
+- Structured artifact output with entry points, data flow, and key files
+- Verbose mode for debugging agent behavior
+- `--no-post` flag for local-only analysis
+
+[Unreleased]: https://github.com/your-org/visible/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/your-org/visible/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visible Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# @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
+
+## 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
+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
+
+### `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
+
+### `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
+
+**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
+
+## 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
+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
+```
+
+## 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.

package/dist/bin/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node