@tyroneross/navgator 0.1.0

package/commands/nav-connections.md

@@ -0,0 +1,58 @@
+---
+description: "Show all connections for a specific component"
+allowed-tools: ["Bash", "Read"]
+arguments:
+  - name: "component"
+    description: "Component name to show connections for"
+    required: true
+---
+
+# NavGator Connection View
+
+Show all incoming and outgoing connections for a specific component.
+
+## Usage
+
+```bash
+npx @tyroneross/navgator connections "<component-name>"
+```
+
+## Examples
+
+**API endpoint connections:**
+```bash
+npx @tyroneross/navgator connections "/api/users"
+# Shows: Database tables this endpoint reads/writes
+# Shows: Frontend components that call this endpoint
+```
+
+**Database table connections:**
+```bash
+npx @tyroneross/navgator connections "users"
+# Shows: All API endpoints that access this table
+# Shows: Queue handlers that modify this table
+```
+
+## Output Format
+
+```
+Component: users (database table)
+Layer: database
+
+INCOMING CONNECTIONS (what connects TO this):
+├── POST /api/users (api-endpoint)
+│   └── src/api/users.ts:45 → createUser()
+├── PUT /api/users/:id (api-endpoint)
+│   └── src/api/users.ts:78 → updateUser()
+└── summarize-worker (queue-handler)
+    └── src/workers/summarize.ts:23 → processJob()
+
+OUTGOING CONNECTIONS (what this connects TO):
+└── None (database tables don't connect outward)
+```
+
+## Options
+
+- `--json`: Output as JSON
+- `--incoming`: Show only incoming connections
+- `--outgoing`: Show only outgoing connections

package/commands/nav-diagram.md

@@ -0,0 +1,106 @@
+---
+name: nav-diagram
+description: Generate a Mermaid diagram of the architecture
+---
+
+# NavGator Diagram Generator
+
+Generate visual architecture diagrams in Mermaid format.
+
+## When to Use
+
+- Visualize the overall architecture before making changes
+- Generate documentation diagrams
+- Understand component relationships at a glance
+- Create focused diagrams around specific components
+
+## Usage
+
+### Full Architecture Diagram
+
+```bash
+npx @tyroneross/navgator diagram
+```
+
+Generates a complete architecture diagram with all components grouped by layer (frontend, backend, database, queue, infrastructure, external).
+
+### Component-Focused Diagram
+
+```bash
+npx @tyroneross/navgator diagram --focus "Stripe"
+```
+
+Generates a diagram centered on a specific component, showing its direct connections.
+
+### Layer Diagram
+
+```bash
+npx @tyroneross/navgator diagram --layer backend
+```
+
+Shows only components in a specific layer and their connections to other layers.
+
+### Summary Diagram
+
+```bash
+npx @tyroneross/navgator diagram --summary
+```
+
+Shows only the most-connected components for a simplified overview.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--focus <name>` | Center diagram on a specific component |
+| `--layer <name>` | Show only a specific layer (frontend, backend, database, queue, infra, external) |
+| `--summary` | Show only top connected components |
+| `--direction <dir>` | Diagram direction: TB, BT, LR, RL (default: TB) |
+| `--no-styles` | Disable color styling |
+| `--no-labels` | Hide connection labels |
+| `--output <file>` | Save to file instead of stdout |
+| `--max-nodes <n>` | Maximum nodes to show (default: 50) |
+
+## Output Format
+
+The diagram is output as Mermaid markdown that can be:
+- Pasted into GitHub/GitLab markdown files
+- Rendered in VS Code with Mermaid extensions
+- Used in documentation tools like Docusaurus, MkDocs
+- Converted to images using mermaid-cli
+
+## Example Output
+
+```mermaid
+graph TB
+  subgraph Frontend
+    COMP_npm_react_a1b2["react"]
+    COMP_npm_nextjs_c3d4["Next.js"]
+  end
+
+  subgraph Backend
+    COMP_npm_express_e5f6["express"]
+  end
+
+  subgraph External Services
+    COMP_service_stripe_g7h8["Stripe"]
+    COMP_service_openai_i9j0["OpenAI"]
+  end
+
+  COMP_npm_nextjs_c3d4 -->|calls| COMP_npm_express_e5f6
+  COMP_npm_express_e5f6 -->|uses| COMP_service_stripe_g7h8
+
+  style COMP_npm_react_a1b2,COMP_npm_nextjs_c3d4 fill:#bbdefb,stroke:#1976d2
+  style COMP_npm_express_e5f6 fill:#c8e6c9,stroke:#388e3c
+  style COMP_service_stripe_g7h8,COMP_service_openai_i9j0 fill:#ffccbc,stroke:#e64a19
+```
+
+## Tips
+
+1. **Run scan first**: Diagrams are generated from the stored architecture data. Run `/nav-scan` first if you haven't already.
+
+2. **Use focus for complex projects**: Large codebases may have too many nodes. Use `--focus` to see specific areas.
+
+3. **Export for documentation**: Use `--output architecture.md` to save directly to your docs folder.
+
+4. **Combine with impact analysis**: After running `/nav-impact <component>`, generate a focused diagram to visualize the affected components.

package/commands/nav-export.md

@@ -0,0 +1,71 @@
+---
+description: "Export architecture to markdown or JSON"
+allowed-tools: ["Bash", "Read", "Write"]
+---
+
+# NavGator Export
+
+Export your project's architecture documentation to markdown or JSON format.
+
+## Usage
+
+```bash
+npx @tyroneross/navgator export [format] [output-file]
+```
+
+## Formats
+
+**Markdown (default):**
+```bash
+npx @tyroneross/navgator export md ARCHITECTURE.md
+```
+
+**JSON:**
+```bash
+npx @tyroneross/navgator export json architecture.json
+```
+
+## Markdown Output Example
+
+```markdown
+# Project Architecture
+
+## Components
+
+### Packages (npm)
+- react (18.2.0) - UI framework
+- next (14.0.0) - React framework
+- @supabase/supabase-js (2.39.0) - Database client
+
+### Infrastructure
+- Railway - Deployment platform
+- Docker - Containerization
+
+### External Services
+- Stripe - Payment processing
+- OpenAI - AI/LLM integration
+
+## Connections
+
+### API → Database
+| Endpoint | Table | File | Line |
+|----------|-------|------|------|
+| POST /api/users | users | src/api/users.ts | 45 |
+| GET /api/orders | orders | src/api/orders.ts | 23 |
+
+### Frontend → API
+| Component | Endpoint | File | Line |
+|-----------|----------|------|------|
+| UserForm | POST /api/users | src/components/UserForm.tsx | 67 |
+
+### AI Prompts
+| Name | File | Line |
+|------|------|------|
+| summarize-article | src/prompts/summarize.ts | 12 |
+```
+
+## Options
+
+- `--components-only`: Export only components, skip connections
+- `--connections-only`: Export only connections
+- `--graph`: Include mermaid diagram of connections

package/commands/nav-impact.md

@@ -0,0 +1,58 @@
+---
+description: "Show what's affected if you change a component"
+allowed-tools: ["Bash", "Read"]
+arguments:
+  - name: "component"
+    description: "Component name to analyze (e.g., 'users-table', 'bullmq', 'stripe')"
+    required: true
+---
+
+# NavGator Impact Analysis
+
+Show what other components and code would be affected if you change a specific component.
+
+**This is the key value of NavGator:** Know what else needs updating before you make a change.
+
+## Usage
+
+```bash
+npx @tyroneross/navgator impact "<component-name>"
+```
+
+## Examples
+
+**Database table change:**
+```bash
+npx @tyroneross/navgator impact "users"
+# Shows: All API endpoints that read/write the users table
+# Shows: File:line references for each connection
+```
+
+**Queue/worker change:**
+```bash
+npx @tyroneross/navgator impact "bullmq"
+# Shows: All handlers triggered by BullMQ jobs
+# Shows: AI prompts called from workers
+```
+
+**External service change:**
+```bash
+npx @tyroneross/navgator impact "stripe"
+# Shows: All files that call Stripe APIs
+# Shows: Frontend components that handle Stripe flows
+```
+
+## Output
+
+For each affected component, you'll see:
+- Component name and type
+- Connection type (api-calls-db, frontend-calls-api, etc.)
+- File path and line number
+- Function name (if detected)
+- Code snippet (truncated)
+
+## Use Cases
+
+1. **Before schema migration:** "If I change the users table, what APIs need updating?"
+2. **Before refactoring:** "If I modify this BullMQ worker, what prompts are affected?"
+3. **Before removing a dependency:** "What code uses this package?"

package/commands/nav-scan.md

@@ -0,0 +1,46 @@
+---
+description: "Scan project architecture and update connection tracking"
+allowed-tools: ["Bash", "Read", "Glob", "Grep"]
+---
+
+# NavGator Architecture Scan
+
+Scan the current project to detect and track architecture components and their connections.
+
+## What Gets Scanned
+
+**Components:**
+- Packages (npm, pip, cargo, go, gem, composer)
+- Frameworks (Next.js, React, Django, FastAPI, etc.)
+- Databases (PostgreSQL, MongoDB, Redis, Supabase)
+- Queues (BullMQ, Celery, SQS)
+- Infrastructure (Railway, Vercel, Docker)
+- External services (Stripe, OpenAI, Twilio)
+
+**Connections:**
+- API → Database (which endpoints touch which tables)
+- Frontend → API (which components call which endpoints)
+- Queue → Handler (which jobs trigger which code)
+- Service calls (where external APIs are used)
+- AI prompts (where Claude/OpenAI calls live, with file:line)
+
+## Run the Scan
+
+```bash
+npx @tyroneross/navgator scan
+```
+
+## Options
+
+- `--quick`: Only scan package files, skip code analysis
+- `--connections`: Focus on connection detection
+- `--verbose`: Show detailed detection output
+
+## After Scanning
+
+Review the detected architecture:
+- Total components found
+- Connections mapped
+- Any potential issues (outdated packages, missing connections)
+
+Use `/nav-status` to see a summary, or `/nav-impact <component>` to see what's affected by a specific component.

package/commands/nav-status.md

@@ -0,0 +1,44 @@
+---
+description: "Show architecture summary and health status"
+allowed-tools: ["Bash", "Read"]
+---
+
+# NavGator Architecture Status
+
+Display a summary of the project's architecture including components, connections, and health status.
+
+## Run Status Check
+
+```bash
+npx @tyroneross/navgator status
+```
+
+## What You'll See
+
+**Component Summary:**
+- Total packages by type (npm, pip, etc.)
+- Frameworks and databases detected
+- Infrastructure and services in use
+
+**Connection Summary:**
+- API → Database connections
+- Frontend → API connections
+- Queue → Handler connections
+- External service calls
+- AI prompt locations
+
+**Health Status (if enabled):**
+- Outdated packages
+- Security vulnerabilities
+- Missing connections
+
+## Options
+
+- `--json`: Output as JSON for programmatic use
+- `--verbose`: Show all components and connections
+
+## Related Commands
+
+- `/nav-scan`: Rescan the project
+- `/nav-impact <component>`: See what's affected by a component
+- `/nav-connections <component>`: See all connections for a component

package/dist/cli/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * NavGator CLI
+ * Architecture connection tracker for Claude Code
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}