ai-summon 0.0.1

package/CLAUDE.md

@@ -0,0 +1,199 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is **hsh19900502**, a TypeScript-based CLI tool that provides Git workflow automation and IDE project management utilities. It's built as an ESM module and designed to be installed globally as a command-line utility.
+
+## Development Setup
+
+### Building and Installation
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the project (TypeScript compilation)
+yarn build
+
+# Build and install globally for testing
+yarn build:install
+
+# Development mode (requires ts-node)
+yarn dev
+
+# Start compiled version
+yarn start
+```
+
+### Key Dependencies
+
+- **commander**: CLI framework for command parsing
+- **inquirer**: Interactive command-line prompts with autocomplete support
+- **zx**: Shell scripting utilities (provides `$` template literal)
+- **chalk**: Terminal string styling
+- **ora**: Terminal spinners and progress indicators
+- **typescript**: TypeScript compiler and language support
+- **ts-node**: TypeScript execution for development
+
+## Architecture
+
+### Project Structure
+
+```text
+src/
+├── hsh.ts              # Main CLI entry point with command definitions
+├── commands/
+│   ├── git.ts          # Git workflow commands (gcm, push, merge, mr, branchout)
+│   ├── mono.ts         # Monorepo management (init, cd)
+│   ├── ide.ts          # IDE integration (cursor, claude)
+│   └── mcp.ts          # MCP server synchronization
+├── types/
+│   └── index.ts        # TypeScript type definitions
+└── util.ts             # Utility functions (package.json reading)
+```
+
+### Command Architecture
+
+The CLI follows a modular command structure using Commander.js:
+
+- **Main commands**: Defined in `hsh.ts` with action handlers
+- **Command modules**: Organized by feature domain (git, mono, ide)
+- **Interactive prompts**: Heavy use of inquirer for user input with validation
+- **Shell integration**: Uses `zx` for executing shell commands with `$` template literals
+
+### Key Design Patterns
+
+- **ESM modules**: Uses ES module imports/exports throughout
+- **Async/await**: All shell operations are async with proper error handling
+- **Interactive CLI**: Extensive use of inquirer prompts with autocomplete
+- **Configuration-based**: IDE command uses `~/.ai/config.json` for project paths
+- **Monorepo aware**: Special handling for multi-repository workflows
+- **TypeScript strict mode**: Full type safety with comprehensive type checking
+
+## Command Categories
+
+### Git Workflow Commands
+
+- `gcm <message> [--push]`: Add all, commit with message, optionally push
+- `push`: Interactive branch selection for pushing to remote
+- `merge <branch>`: Safe merge with branch switching and pulling
+- `mr create`: Create merge requests with JIRA integration (uses `glab`)
+- `branchout <branch>`: Create new branch from master
+
+### Monorepo Management
+
+- `mono init`: Initialize workspace with `.hsh` marker file
+- `mono cd <level> [--repo <name>]`: Navigate to repo directories (root/client/server)
+
+### IDE Integration
+
+- `cursor`: Open project in Cursor editor with config-based project selection
+
+### MCP Server Management
+
+- `mcp sync`: Synchronize MCP server configurations from `~/.mcp/servers.json` to all projects in `~/.claude.json`
+  - This addresses the limitation that Claude Code cannot install MCP servers globally
+  - Automatically updates all project configurations with centralized MCP server definitions
+  - Idempotent operation - safe to run multiple times
+  - Useful for maintaining consistent MCP configurations across multiple projects
+
+## Configuration Requirements
+
+### IDE Configuration
+
+The `cursor` and `claude` commands require a configuration file at `~/.ai/config.json`:
+
+```json
+{
+  "category1": {
+    "project1": "/path/to/project1",
+    "project2": "/path/to/project2"
+  },
+  "category2": {
+    "project3": "/path/to/project3"
+  }
+}
+```
+
+### Monorepo Setup
+
+For monorepo commands, projects should have:
+
+- `.hsh` marker file in the root (created by `mono init`)
+- Directory structure: `<repo-name>/client/` and `<repo-name>/server/`
+
+### MCP Server Configuration
+
+MCP (Model Context Protocol) servers can be centrally managed:
+
+- Create `~/.mcp/servers.json` with your global MCP server configurations
+- Run `hsh mcp sync` to propagate configurations to all projects in `~/.claude.json`
+- Each project's `mcpServers` field will be updated with the latest configuration
+
+Example `~/.mcp/servers.json`:
+
+```json
+{
+  "chrome-devtools": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["chrome-devtools-mcp@latest"],
+    "env": {}
+  },
+  "GitLab communication server": {
+    "command": "npx",
+    "args": ["-y", "@zereight/mcp-gitlab"],
+    "env": {
+      "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token",
+      "GITLAB_API_URL": "https://gitlab.example.com/api/v4"
+    }
+  }
+}
+```
+
+## External Dependencies
+
+### Required CLI Tools
+
+- **git**: For all git operations
+- **glab**: GitLab CLI for merge request creation (used in `mr create`)
+- **cursor**: Cursor editor executable (for `cursor` command)
+
+### Shell Integration
+
+- Commands extensively use shell execution via `zx`
+- Relies on system PATH for external tools
+- Uses `process.chdir()` for directory navigation in monorepo commands
+
+## Development Patterns
+
+### Error Handling
+
+- Uses chalk for colored terminal output (green for success, yellow for warnings)
+- Interactive prompts include validation functions
+- Shell commands use async/await with implicit error propagation
+
+### User Experience
+
+- Extensive use of default values in prompts (e.g., current branch for push)
+- Autocomplete support for directory/project selection
+- Branch name parsing for JIRA integration in MR creation
+- Progress feedback with colored console output
+
+### TypeScript Configuration
+
+- Strict mode enabled with comprehensive type checking
+- ESNext module resolution with bundler strategy
+- Declaration files generated for distribution
+- Paths configuration for clean imports
+- Uses ES2020 target with modern JavaScript features
+
+## Important Notes
+
+- All commands use **Yarn** as the package manager
+- Built as ES modules with `.js` extensions in imports
+- Requires Node.js with ES module support
+- TypeScript compilation outputs to `dist/` directory with declaration files
+- Pls ensure no ts error or eslint error after each code change

package/PRD.md

@@ -0,0 +1,268 @@
+# Product Requirements Document: IDE Command Enhancement
+
+## Overview
+
+This PRD describes enhancements to the IDE integration commands (`hsh cursor` and `hsh claude`) to support automatic Git repository discovery through a configurable working directory approach.
+
+## Problem Statement
+
+Currently, users must manually configure every project path in `~/.ai/config.json` under category structures. This becomes cumbersome when managing many Git repositories, especially in environments with multiple projects organized under common parent directories.
+
+## Proposed Solution
+
+Introduce a `workingDirectory` configuration option in `~/.ai/config.json` that enables automatic Git repository discovery. When configured, the IDE commands will automatically scan for Git repositories (directories containing `.git` folders) within the specified working directory.
+
+## Requirements
+
+### Functional Requirements
+
+#### FR1: Working Directory Configuration
+- **Description**: Support optional `workingDirectory` field in `~/.ai/config.json`
+- **Behavior**: When set, `workingDirectory` takes precedence and the system ONLY uses auto-discovered Git repositories
+- **Precedence Rule**: If `workingDirectory` exists, manually configured category-based projects are ignored
+- **Example Configuration**:
+  ```json
+  {
+    "workingDirectory": "/Users/username/dev"
+  }
+  ```
+
+#### FR2: Automatic Git Repository Discovery
+- **Description**: Scan working directory for subdirectories containing `.git` folders
+- **Behavior**: 
+  - Recursively search for `.git` folders within the working directory
+  - Treat each `.git` folder as a project root marker
+  - Stop recursive search when `.git` is found (don't search deeper within Git repos)
+- **Output**: Generate a list of discovered Git repositories for project selection
+
+#### FR3: Project Selection Interface
+- **Description**: Present discovered projects in the interactive prompt
+- **Behavior**:
+  - Display all auto-discovered Git repositories from working directory
+  - Use autocomplete-enabled inquirer prompt
+  - Show project name (directory name) and full path for clarity
+  - Format: `project-name (/full/path/to/project-name)`
+
+#### FR4: Backward Compatibility
+- **Description**: Ensure existing configurations continue to work without modification
+- **Behavior**:
+  - If `workingDirectory` is NOT configured → use manual project configurations (existing behavior)
+  - If `workingDirectory` IS configured → ignore manual configurations, use only auto-discovery
+  - Existing category-based project structures remain fully functional when `workingDirectory` is absent
+  - No breaking changes to current user workflows
+
+### Non-Functional Requirements
+
+#### NFR1: Performance
+- Repository scanning should complete within reasonable time (< 5 seconds for typical directories)
+- Consider implementing caching if scan performance becomes an issue
+
+#### NFR2: Error Handling
+- Gracefully handle permission errors when scanning directories
+- Provide clear error messages if `workingDirectory` path doesn't exist
+- Continue operation even if some subdirectories are inaccessible
+
+#### NFR3: User Experience
+- Clear and consistent project listing format
+- Fast autocomplete search functionality
+- Alphabetically sorted project list
+- Helpful defaults and suggestions
+
+## Configuration Schema
+
+### Enhanced `~/.ai/config.json` Structure
+
+**Option 1: With Working Directory (Auto-Discovery Mode)**
+```json
+{
+  "workingDirectory": "/Users/username/dev/projects"
+}
+```
+
+**Option 2: Without Working Directory (Manual Configuration Mode - Existing Behavior)**
+```json
+{
+  "category1": {
+    "manually-configured-project": "/path/to/project"
+  },
+  "category2": {
+    "another-project": "/different/path"
+  }
+}
+```
+
+### Configuration Precedence
+- **If `workingDirectory` is present**: Use ONLY auto-discovered Git repositories, ignore manual configurations
+- **If `workingDirectory` is absent**: Use manual category-based project configurations (existing behavior)
+
+## Implementation Notes
+
+### Target File
+- **File**: `src/commands/ide/index.ts`
+- **Affected Functions**: Project discovery and selection logic
+
+### Technical Approach
+1. Add `workingDirectory` field to configuration type definition
+2. Implement Git repository scanner utility function
+3. Modify project loading logic:
+   - Check if `workingDirectory` exists in config
+   - If yes: use auto-discovered projects only
+   - If no: use manual configurations (existing behavior)
+4. Update inquirer prompts to display discovered projects
+5. Ensure backward compatibility by making `workingDirectory` optional
+
+### Git Repository Detection
+- Use Node.js `fs` module to recursively scan directories
+- Check for `.git` folder existence using `fs.existsSync()`
+- Stop recursion at `.git` boundaries to avoid scanning repo contents
+- Extract project name from directory name
+
+## Success Criteria
+
+1. ✅ Users can configure `workingDirectory` and auto-discover Git repos
+2. ✅ When `workingDirectory` is set, manual configurations are ignored (precedence working correctly)
+3. ✅ When `workingDirectory` is absent, existing manual configurations work unchanged
+4. ✅ Auto-discovered project list appears in IDE command prompts
+5. ✅ No TypeScript or ESLint errors introduced
+6. ✅ Backward compatible with existing `~/.hsh/config.json` files (legacy location)
+7. ✅ Clear error handling for edge cases
+
+## Out of Scope
+
+- Ignoring specific directories (e.g., `node_modules`) - can be added later
+- Caching of discovered repositories - performance optimization for future
+- Multiple working directories - single directory for MVP
+- GUI configuration management - remains CLI-based
+
+## Open Questions
+
+### Q1: Project Display Format
+When displaying auto-discovered projects in the inquirer prompt, what format should be used?
+
+**Option A: Simple format (directory name with path)**
+```
+? Select a project: (Use arrow keys or type to search)
+❯ my-awesome-project (/Users/username/dev/my-awesome-project)
+  another-repo (/Users/username/dev/another-repo)
+  cool-app (/Users/username/dev/nested/cool-app)
+```
+
+**Option B: Show relative path from working directory**
+```
+? Select a project: (Use arrow keys or type to search)
+❯ my-awesome-project (./my-awesome-project)
+  another-repo (./another-repo)
+  cool-app (./nested/cool-app)
+```
+
+**Option C: Directory name only, with full path on selection**
+```
+? Select a project: (Use arrow keys or type to search)
+❯ my-awesome-project
+  another-repo
+  cool-app
+
+Selected: /Users/username/dev/my-awesome-project
+```
+
+**Option D: Flattened list with top-level folder separators (SELECTED)**
+```
+? Select a project: (Use arrow keys or type to search)
+  --------- work ---------
+❯ project-a (/Users/username/dev/work/project-a)
+  project-b (/Users/username/dev/work/project-b)
+  --------- personal ---------
+  my-app (/Users/username/dev/personal/my-app)
+  my-tool (/Users/username/dev/personal/my-tool)
+  --------- / (root) ---------
+  standalone-repo (/Users/username/dev/standalone-repo)
+```
+- Pro: Visual organization while maintaining flat, searchable list
+- Pro: Shows top-level folder context without nested tree structure
+- Pro: Works well with autocomplete search (separators are ignored/filtered out)
+- Pro: Easy to scan and understand repository organization
+
+**Your Answer:** **D** - Flattened list with visual separators for top-level folders
+
+---
+
+### Q2: Project Naming for Auto-Discovered Repositories
+Auto-discovered projects use the directory name as the project name (e.g., `/Users/username/dev/my-repo` → display as "my-repo"). Should users be able to customize these names?
+
+No, no need to customize
+
+---
+
+### Q3: Repository Scanning Strategy
+Git repository discovery could be expensive if working directory has many nested folders. When should scanning happen?
+
+**Option A: Scan on every command execution (always fresh) - SELECTED**
+- Pro: Always shows latest repositories, handles newly cloned repos immediately
+- Pro: For 200 repos, scan takes ~300-800ms (barely noticeable)
+- Pro: Simple implementation, no cache management complexity
+- Con: May have slight delay on each command execution
+- **Performance notes**: 
+  - Flat structure (200 repos at depth 1): ~100-300ms
+  - Typical structure (2-3 levels deep): ~300-800ms
+  - Can optimize by skipping `node_modules`, `dist`, `.git` internals if needed
+
+**Option B: Scan once and cache results (with manual refresh command)**
+- Add `hsh refresh` or `hsh ide refresh` command to rebuild cache
+- Pro: Fast command execution
+- Con: Users must remember to refresh after cloning new repos
+
+**Option C: Smart caching with TTL (e.g., cache for 1 hour)**
+- Cache results but auto-refresh after time threshold
+- Pro: Balance between performance and freshness
+- Con: More complex implementation
+
+**Option D: Scan on-demand with progress indicator**
+- Show spinner/progress while scanning: "🔍 Discovering repositories..."
+- Pro: Users know why there's a delay, always fresh
+- Con: For typical use (200 repos), overhead of showing spinner (~300-800ms) may not be worth it
+
+**Your Answer:** **A** - Scan on every command execution. With 200 repos, the 300-800ms scan time is barely noticeable and provides the best user experience (always fresh, no cache maintenance needed).
+
+---
+
+### Q4: Nested Git Repository Handling
+What should happen when a Git repository contains other Git repositories (e.g., Git submodules)?
+
+**Answer:** Not a concern for MVP. The natural scanning behavior handles this correctly:
+- When `.git` folder is found, mark that directory as a repository
+- Stop recursing into that directory's subdirectories
+- This automatically prevents scanning inside repositories
+- Edge case of nested repos (submodules, manually nested repos) is rare enough to ignore
+
+**Implementation note**: The recursive scanner will:
+```typescript
+// Pseudo-code
+function findGitRepos(dir) {
+  if (containsGitFolder(dir)) {
+    return [dir]; // Found a repo, stop recursing
+  }
+  
+  // Continue scanning subdirectories
+  return subdirs.flatMap(subdir => findGitRepos(subdir));
+}
+```
+
+This naturally handles the nested case without special logic.
+
+---
+
+### Q5: Error Handling for Inaccessible Directories
+During scanning, some directories might be inaccessible due to permissions or symlink issues. How should the system behave?
+
+**Answer:** Handle in future iteration. For MVP:
+- Let Node.js filesystem errors propagate naturally
+- Most users won't encounter permission issues in their working directory
+- Can add proper error handling (silent skip, warnings, etc.) based on real-world feedback
+
+**Your Answer:** Defer to future iteration - not critical for MVP
+
+## References
+
+- Existing Implementation: `src/commands/ide/index.ts`
+- Configuration File: `~/.ai/config.json`
+- Related Commands: `hsh cursor`, `hsh claude` 

package/README.md

@@ -0,0 +1,171 @@
+# ai-summon
+
+A small TypeScript CLI (binary name: `ai`) for:
+
+- Opening projects in **Cursor** or **Claude** via an interactive fuzzy search
+- Managing personal **URL bookmarks** and **URL groups** (open in Chrome)
+- Bootstrapping `~/.ai/config.json`
+
+## Installation
+
+```bash
+yarn install
+yarn build:install
+```
+
+After install, you should have the `ai` command available:
+
+```bash
+ai --help
+```
+
+## Commands
+
+### `ai init`
+
+Initialize `~/.ai/config.json`.
+
+```bash
+ai init
+ai init --working-directory /Users/you/dev
+ai init --force
+```
+
+Options:
+
+- `-w, --working-directory <path>`: set `workingDirectory` without prompting
+- `-f, --force`: overwrite existing config without confirmation
+
+### `ai cursor [search]`
+
+Open a project in **Cursor**.
+
+```bash
+ai cursor
+ai cursor payments
+```
+
+### `ai claude [search]`
+
+Open a project in **Claude Code**.
+
+```bash
+ai claude
+ai claude impactful
+```
+
+### `ai cursor refresh` / `ai claude refresh`
+
+Refresh the cached auto-discovered repositories (only applies when `workingDirectory` mode is enabled).
+
+```bash
+ai cursor refresh
+ai claude refresh
+```
+
+### `ai url ...`
+
+URL bookmark management (stored in `~/.ai/config.json`).
+
+#### `ai url add <name> <url>`
+
+```bash
+ai url add jira https://your-jira.example.com
+```
+
+#### `ai url remove [name]`
+
+If `name` is omitted, you’ll enter interactive search mode.
+
+```bash
+ai url remove jira
+ai url remove
+```
+
+#### `ai url search [--suppress]`
+
+Interactively search bookmarks and open the selected URL in **Google Chrome**.
+
+```bash
+ai url search
+ai url search --suppress
+```
+
+Options:
+
+- `--suppress`: auto-dismiss popups by simulating the Enter key after opening (macOS via `osascript`)
+
+#### `ai url group`
+
+Select a configured URL group and open all URLs in a new Chrome window.
+
+```bash
+ai url group
+```
+
+## Configuration (`~/.ai/config.json`)
+
+Run `ai init` to create the file. The CLI supports **two modes** for project selection:
+
+### Auto-discovery mode (recommended)
+
+Set `workingDirectory` to a folder containing your git repositories. The CLI will recursively scan for repos (by `.git`) and cache results to speed up future runs (cache file: `~/.ai/ide-repos-cache.json`).
+
+Example:
+
+```json
+{
+  "workingDirectory": "/Users/you/dev",
+  "repos": {},
+  "yiren": {},
+  "urls": {},
+  "urlGroups": {}
+}
+```
+
+### Manual mode (grouped projects)
+
+If `workingDirectory` is not set, `ai cursor` / `ai claude` will use `repos` (two-step selection: category → project).
+
+Example:
+
+```json
+{
+  "repos": {
+    "work": {
+      "impactful": "/Users/you/dev/impactful",
+      "payments": "/Users/you/dev/payments"
+    },
+    "personal": {
+      "dotfiles": "/Users/you/dev/dotfiles"
+    }
+  },
+  "yiren": {},
+  "urls": {
+    "jira": "https://your-jira.example.com",
+    "gitlab": "https://your-gitlab.example.com"
+  },
+  "urlGroups": {
+    "daily": ["https://example.com", "https://example.org"]
+  }
+}
+```
+
+## Development
+
+```bash
+yarn install
+yarn build
+yarn dev
+```
+
+## Requirements / Notes
+
+- **Node.js**: required to run the CLI
+- **Cursor**: `ai cursor` shells out to `cursor <path>`
+- **Claude Code**: `ai claude` shells out to `claude` (and runs it in the selected repo directory)
+- **Chrome + macOS**: `ai url ...` currently uses `open -a "Google Chrome" ...` (and `osascript` for `--suppress`)
+
+## License
+
+ISC

package/dist/ai-summon.d.ts

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