@gitton-dev/types 0.0.0

package/README.md

@@ -0,0 +1,170 @@
+# Gitton
+
+**Git Client for Vibe Coding**
+
+Gitton is a Git client designed for the AI coding era. Run Claude Code, Cursor CLI, and other AI assistants directly in the integrated terminal. Features AI-powered commit message generation, code review, and PR description generation.
+
+![Gitton Working Copy](https://jsers.dev/images/gitton-working-copy.png)
+
+## Philosophy
+
+Gitton represents a paradigm shift in development tools for the AI era. With AI coding assistants like Claude Code, Cursor CLI, and Aider, developers spend less time in traditional editors and more time in terminals.
+
+**Terminal-First Approach** - Rather than another code editor, Gitton integrates a terminal for AI instruction. Give instructions to AI in the terminal, review results and commit in a powerful Git client.
+
+**Advanced Git Features** - AI-assisted development requires *more* sophisticated Git capabilities. Since AI generates large code blocks that may include unintended changes, you need granular version control.
+
+**GitHub-Exclusive Focus** - Deep GitHub integration enables PR management, inline commenting, AI-generated PR descriptions, and automated code reviews—all within the app.
+
+**Strip unnecessary features while thoroughly refining essential ones.** For the AI era, that means: powerful Git operations, terminal integration, and seamless GitHub workflows—without editor complexity.
+
+## Features
+
+### Visual History & Navigation
+
+![Gitton History](https://jsers.dev/images/gitton-history.png)
+
+- **Intuitive Graph View** - Visualize your project history with color-coded branch graphs
+- **Easy Operations** - Cherry-pick, revert, and reset commits with a click
+- **Reflog Support** - Complete operation history for easy recovery from mistakes
+
+### Branches & Reflog
+
+![Gitton Branches](https://jsers.dev/images/gitton-branches.png)
+
+### GitHub Integration
+
+![Gitton Pull Requests](https://jsers.dev/images/gitton-pull-requests.png)
+
+- **Pull Requests** - Create, review, and merge PRs without leaving the app
+- **AI-Generated PR Descriptions** - Let AI write your PR descriptions from commit diffs
+- **AI Code Review** - Get intelligent feedback on your changes
+
+![Gitton AI Review](https://jsers.dev/images/gitton-ai-review.png)
+
+### AI-Powered Workflows
+
+- **Multi-Provider Support** - OpenAI, Anthropic, Google, and Ollama
+- **Conventional Commit Messages** - Auto-generate meaningful commit messages
+- **Security Analysis** - AI-powered security scanning of your changes
+
+### Parallel Development with Worktrees
+
+![Gitton Worktrees](https://jsers.dev/images/gitton-worktrees.png)
+
+- **Multiple Worktrees** - Work on different branches simultaneously
+- **Independent Sessions** - Run separate AI tool sessions in each worktree
+
+### Integrated Terminal
+
+![Gitton Terminal](https://jsers.dev/images/gitton-terminal.png)
+
+- **AI Tool Ready** - Claude Code, Cursor, GitHub Copilot - use any tool you like
+- **Full Shell Access** - Execute any command within your repository
+
+### Plugin System
+
+Extend Gitton's functionality with plugins:
+- Add custom sidebar panels
+- Add settings tabs
+- Add context menu items
+- Register Git hooks (pre-commit, post-push, etc.)
+
+## Plugin Development
+
+Create plugins to extend Gitton. See `gitton-plugin.d.ts` for TypeScript definitions.
+
+### Plugin Structure
+
+```
+my-gitton-plugin/
+├── package.json        # Plugin manifest in "gitton" field
+├── ui/
+│   └── sidebar.html    # UI extension HTML
+└── ...
+```
+
+### package.json Example
+
+```json
+{
+  "name": "gitton-plugin-example",
+  "version": "1.0.0",
+  "gitton": {
+    "displayName": "Example Plugin",
+    "version": "1.0.0",
+    "description": "An example plugin for Gitton",
+    "permissions": ["ui:sidebar", "settings:read", "settings:write"],
+    "extensionPoints": {
+      "sidebar": {
+        "entry": "ui/sidebar.html",
+        "icon": "Puzzle",
+        "position": "bottom"
+      }
+    }
+  }
+}
+```
+
+### Plugin API
+
+Access the `gitton` global object in your plugin HTML:
+
+```typescript
+// Settings
+const value = await gitton.settings.get('myKey');
+await gitton.settings.set('myKey', { foo: 'bar' });
+
+// Notifications
+gitton.ui.showNotification('Hello!', 'info');
+
+// Open external URL
+await gitton.ui.openExternal('https://github.com');
+
+// HTTP requests
+const result = await gitton.network.fetch('https://api.example.com/data');
+
+// GitHub CLI
+const prList = await gitton.gh.run(['pr', 'list', '--json', 'number,title']);
+
+// File system (within repo only)
+const content = await gitton.fs.readFile('.gitignore');
+await gitton.fs.writeFile('temp.txt', 'content');
+```
+
+### Permissions
+
+| Permission | Description |
+|------------|-------------|
+| `ui:sidebar` | Add sidebar panel |
+| `ui:settings` | Add settings tab |
+| `ui:repositorySettings` | Add repository settings tab |
+| `ui:contextMenu` | Add context menu items |
+| `settings:read` | Read plugin settings |
+| `settings:write` | Write plugin settings |
+| `network:fetch` | Make HTTP requests |
+| `git:read` | Read Git information |
+| `git:write` | Execute Git operations |
+| `git:hooks` | Register Git hooks |
+
+### Marketplace
+
+Publish your plugin on GitHub with the `gitton-plugin` topic to appear in the Gitton marketplace.
+
+## Pricing
+
+- **Free Trial** - 7 days
+- **Pro** - $19.99 one-time purchase (no subscription)
+
+## Links
+
+- [Website](https://jsers.dev/service/gitton)
+- [Philosophy](https://jsers.dev/service/gitton/blog/gitton-philosophy)
+
+## License
+
+MIT License
+
+## Author
+
+godai

package/gitton-plugin.d.ts

@@ -0,0 +1,399 @@
+/**
+ * Gitton Plugin API Type Definitions
+ *
+ * This file provides TypeScript type definitions for developing Gitton plugins.
+ * Include this file in your plugin project to get full IntelliSense support.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Plugin permissions that can be requested in package.json
+ */
+export type PluginPermission =
+  | 'ui:sidebar'
+  | 'ui:settings'
+  | 'ui:repositorySettings'
+  | 'ui:contextMenu'
+  | 'settings:read'
+  | 'settings:write'
+  | 'network:fetch'
+  | 'git:read'
+  | 'git:write'
+  | 'git:hooks'
+
+/**
+ * Git hook types that plugins can register
+ */
+export type HookType =
+  | 'preCommit'
+  | 'postCommit'
+  | 'preCheckout'
+  | 'postCheckout'
+  | 'prePush'
+  | 'postPush'
+  | 'preMerge'
+  | 'postMerge'
+  | 'onRepositoryOpen'
+  | 'onRepositoryClose'
+
+/**
+ * Notification types for UI notifications
+ */
+export type NotificationType = 'info' | 'warning' | 'error'
+
+/**
+ * Context menu target types
+ */
+export type ContextMenuTarget = 'commit' | 'file' | 'branch' | 'tag' | 'stash'
+
+/**
+ * Theme setting
+ */
+export type Theme = 'light' | 'dark' | 'system'
+
+/**
+ * Sidebar extension configuration
+ */
+export interface SidebarExtension {
+  /** HTML file path relative to plugin root */
+  entry: string
+  /** Lucide icon name (e.g., "Puzzle", "Settings", "GitBranch") */
+  icon?: string
+  /** Position in sidebar */
+  position?: 'top' | 'bottom'
+}
+
+/**
+ * Settings tab extension configuration
+ */
+export interface SettingsTabExtension {
+  /** HTML file path relative to plugin root */
+  entry: string
+  /** Tab label displayed in settings */
+  label: string
+}
+
+/**
+ * Repository settings extension configuration
+ */
+export interface RepositorySettingsExtension {
+  /** HTML file path relative to plugin root */
+  entry: string
+  /** Tab label displayed in repository settings */
+  label: string
+  /** Lucide icon name */
+  icon?: string
+}
+
+/**
+ * Context menu extension configuration
+ */
+export interface ContextMenuExtension {
+  /** Unique identifier for the menu item */
+  id: string
+  /** Display label for the menu item */
+  label: string
+  /** Contexts where this menu item should appear */
+  context: ContextMenuTarget[]
+}
+
+/**
+ * Extension points configuration
+ */
+export interface ExtensionPoints {
+  sidebar?: SidebarExtension
+  settingsTab?: SettingsTabExtension
+  repositorySettings?: RepositorySettingsExtension
+  contextMenu?: ContextMenuExtension[]
+}
+
+/**
+ * Plugin manifest (gitton field in package.json)
+ */
+export interface PluginManifest {
+  /** Display name shown in Gitton UI */
+  displayName: string
+  /** Plugin version (semver) */
+  version: string
+  /** Plugin description */
+  description?: string
+  /** Plugin author */
+  author?: string
+  /** Plugin icon (Lucide icon name) */
+  icon?: string
+  /** Minimum Gitton version required */
+  minGittonVersion?: string
+  /** Permissions required by the plugin */
+  permissions: PluginPermission[]
+  /** Git hooks the plugin wants to register */
+  hooks?: HookType[]
+  /** UI extension points */
+  extensionPoints?: ExtensionPoints
+  /** JSON Schema for plugin configuration */
+  configSchema?: Record<string, unknown>
+}
+
+/**
+ * Context provided to hooks
+ */
+export interface HookContext {
+  /** Repository path */
+  repoPath: string
+  /** Current branch name */
+  currentBranch?: string
+  /** Additional data depending on hook type */
+  data: Record<string, unknown>
+}
+
+/**
+ * Result returned from hook handlers
+ */
+export interface HookResult {
+  /** Set to false to cancel the operation */
+  proceed: boolean
+  /** Message to show to the user */
+  message?: string
+  /** Modified data to pass to subsequent hooks/operations */
+  modifiedData?: Record<string, unknown>
+}
+
+/**
+ * Context provided to plugin UI
+ */
+export interface GittonContext {
+  /** Current repository path (null if no repo is open) */
+  repoPath: string | null
+  /** Current theme */
+  theme: Theme
+}
+
+/**
+ * Network fetch result
+ */
+export interface FetchResult {
+  /** HTTP status code */
+  status: number
+  /** HTTP status text */
+  statusText: string
+  /** Response headers */
+  headers: Record<string, string>
+  /** Response body as text */
+  body: string
+}
+
+/**
+ * GitHub CLI execution result
+ */
+export interface GhResult {
+  /** Exit code */
+  exitCode: number
+  /** Standard output */
+  stdout: string
+  /** Standard error */
+  stderr: string
+}
+
+/**
+ * Directory entry from readdir
+ */
+export interface DirEntry {
+  /** Entry name */
+  name: string
+  /** Whether it's a directory */
+  isDirectory: boolean
+  /** Whether it's a file */
+  isFile: boolean
+}
+
+/**
+ * Settings API for reading and writing plugin settings
+ */
+export interface SettingsAPI {
+  /**
+   * Get a setting value
+   * @param key - Setting key
+   * @returns The setting value, or undefined if not set
+   */
+  get(key: string): Promise<unknown>
+
+  /**
+   * Set a setting value
+   * @param key - Setting key
+   * @param value - Setting value (must be JSON-serializable)
+   */
+  set(key: string, value: unknown): Promise<void>
+
+  /**
+   * Get all settings for this plugin
+   * @returns Object containing all settings
+   */
+  getAll(): Promise<Record<string, unknown>>
+}
+
+/**
+ * UI API for interacting with Gitton's user interface
+ */
+export interface UIAPI {
+  /**
+   * Show a notification to the user
+   * @param message - Message to display
+   * @param type - Notification type (default: 'info')
+   */
+  showNotification(message: string, type?: NotificationType): void
+
+  /**
+   * Open an external URL in the default browser
+   * @param url - URL to open
+   */
+  openExternal(url: string): Promise<void>
+
+  /**
+   * Get the current theme
+   * @returns Current theme setting
+   */
+  getTheme(): Promise<Theme>
+}
+
+/**
+ * Network API for making HTTP requests
+ */
+export interface NetworkAPI {
+  /**
+   * Make an HTTP request
+   * @param url - Request URL
+   * @param options - Fetch options (method, headers, body, etc.)
+   * @returns Response object
+   */
+  fetch(url: string, options?: RequestInit): Promise<FetchResult>
+}
+
+/**
+ * GitHub CLI API
+ */
+export interface GhAPI {
+  /**
+   * Run a GitHub CLI command
+   * @param args - Command arguments (e.g., ['pr', 'list', '--json', 'number'])
+   * @returns Command result
+   * @example
+   * const result = await gitton.gh.run(['pr', 'list', '--json', 'number,title']);
+   * const prs = JSON.parse(result.stdout);
+   */
+  run(args: string[]): Promise<GhResult>
+}
+
+/**
+ * File system API (restricted to repository directory)
+ */
+export interface FsAPI {
+  /**
+   * Read a file
+   * @param path - File path relative to repository root
+   * @returns File contents as string
+   */
+  readFile(path: string): Promise<string>
+
+  /**
+   * Write a file
+   * @param path - File path relative to repository root
+   * @param content - Content to write
+   */
+  writeFile(path: string, content: string): Promise<void>
+
+  /**
+   * List directory contents
+   * @param path - Directory path relative to repository root
+   * @returns Array of directory entries
+   */
+  readdir(path: string): Promise<DirEntry[]>
+
+  /**
+   * Check if a file or directory exists
+   * @param path - Path relative to repository root
+   * @returns True if exists
+   */
+  exists(path: string): Promise<boolean>
+
+  /**
+   * Delete a file
+   * @param path - File path relative to repository root
+   */
+  unlink(path: string): Promise<void>
+
+  /**
+   * Change file permissions
+   * @param path - File path relative to repository root
+   * @param mode - Permission mode (e.g., 0o755)
+   */
+  chmod(path: string, mode: number): Promise<void>
+}
+
+/**
+ * Main Gitton Plugin API
+ *
+ * This object is available as `window.gitton` in plugin HTML files.
+ */
+export interface GittonPluginAPI {
+  /** Plugin ID assigned by Gitton */
+  readonly pluginId: string
+
+  /** Settings API */
+  readonly settings: SettingsAPI
+
+  /** UI API */
+  readonly ui: UIAPI
+
+  /** Network API */
+  readonly network: NetworkAPI
+
+  /** GitHub CLI API */
+  readonly gh: GhAPI
+
+  /** File system API */
+  readonly fs: FsAPI
+
+  /** Current context (updated when repository changes) */
+  readonly context: GittonContext
+}
+
+/**
+ * Context change event detail
+ */
+export interface ContextChangeEventDetail {
+  repoPath: string | null
+  theme: Theme
+}
+
+declare global {
+  interface Window {
+    /**
+     * Gitton Plugin API
+     *
+     * Available in all plugin HTML files loaded by Gitton.
+     *
+     * @example
+     * // Read a setting
+     * const value = await gitton.settings.get('myKey');
+     *
+     * // Show a notification
+     * gitton.ui.showNotification('Hello from plugin!', 'info');
+     *
+     * // Make an HTTP request
+     * const result = await gitton.network.fetch('https://api.example.com/data');
+     *
+     * // Run GitHub CLI command
+     * const prs = await gitton.gh.run(['pr', 'list', '--json', 'number']);
+     */
+    gitton: GittonPluginAPI
+  }
+
+  interface WindowEventMap {
+    /**
+     * Fired when the context changes (e.g., repository opened/closed, theme changed)
+     */
+    'gitton:contextchange': CustomEvent<ContextChangeEventDetail>
+  }
+}
+
+export {}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gitton-dev/types",
+  "version": "0.0.0",
+  "description": "TypeScript type definitions for Gitton plugins",
+  "main": "gitton-plugin.d.ts",
+  "types": "gitton-plugin.d.ts",
+  "files": [
+    "gitton-plugin.d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "gitton",
+    "gitton-plugin",
+    "typescript",
+    "types"
+  ],
+  "author": "godai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:gitton-dev/gitton-plugins.git",
+    "directory": "packages/types"
+  },
+  "bugs": {
+    "url": "https://github.com/gitton-dev/gitton-plugins/issues"
+  },
+  "homepage": "https://jsers.dev/service/gitton"
+}